Merge pull request #915 from jlowin/integrations

docs/docs.json

@@ -124,9 +124,11 @@
                 "group": "Integrations",
                 "pages": [
                   "integrations/anthropic",
+                  "integrations/chatgpt",
+                  "integrations/claude-code",
                   "integrations/claude-desktop",
-                  "integrations/openai",
                   "integrations/gemini",
+                  "integrations/openai",
                   "integrations/contrib"
                 ]
               },

docs/integrations/anthropic.mdx

@@ -31,7 +31,7 @@ def roll_dice(n_dice: int) -> list[int]:
     return [random.randint(1, 6) for _ in range(n_dice)]
 
 if __name__ == "__main__":
-    mcp.run(transport="sse", port=8000)
+    mcp.run(transport="streamable-http", port=8000)
 ```
 
 ## Deploy the Server
@@ -70,7 +70,7 @@ You'll also need to authenticate with Anthropic. You can do this by setting the
 export ANTHROPIC_API_KEY="your-api-key"
 ```
 
-Here is an example of how to call your server from Python. Note that you'll need to replace `https://your-server-url.com` with the actual URL of your server. In addition, we use `/sse` as the endpoint because we deployed an SSE server with the default path; you may need to use a different endpoint if you customized your server's deployment. **At this time you must also include the `extra_headers` parameter with the `anthropic-beta` header.**
+Here is an example of how to call your server from Python. Note that you'll need to replace `https://your-server-url.com` with the actual URL of your server. In addition, we use `/mcp/` as the endpoint because we deployed a streamable-HTTP server with the default path; you may need to use a different endpoint if you customized your server's deployment. **At this time you must also include the `extra_headers` parameter with the `anthropic-beta` header.**
 
 ```python {5, 13-22}
 import anthropic
@@ -88,7 +88,7 @@ response = client.beta.messages.create(
     mcp_servers=[
         {
             "type": "url",
-            "url": f"{url}/sse",
+            "url": f"{url}/mcp/",
             "name": "dice-server",
         }
     ],
@@ -175,7 +175,7 @@ def roll_dice(n_dice: int) -> list[int]:
 
 if __name__ == "__main__":
     print(f"\n---\n\n🔑 Dice Roller access token:\n\n{access_token}\n\n---\n")
-    mcp.run(transport="sse", port=8000)
+    mcp.run(transport="streamable-http", port=8000)
 ```
 
 ### Client Authentication
@@ -213,7 +213,7 @@ response = client.beta.messages.create(
     mcp_servers=[
         {
             "type": "url",
-            "url": f"{url}/sse",
+            "url": f"{url}/mcp/",
             "name": "dice-server",
             "authorization_token": access_token
         }

docs/integrations/chatgpt.mdx

@@ -0,0 +1,158 @@
+---
+title: ChatGPT + FastMCP
+sidebarTitle: ChatGPT
+description: Connect FastMCP servers to ChatGPT Deep Research
+icon: message-smile
+tag: NEW
+---
+
+ChatGPT supports MCP servers through remote HTTP connections, allowing you to extend ChatGPT's capabilities with custom tools and knowledge from your FastMCP servers.
+
+<Note>
+MCP integration with ChatGPT is currently limited to **Deep Research** functionality and is not available for general chat. This feature is available for ChatGPT Pro, Team, Enterprise, and Edu users.
+</Note>
+
+<Tip>
+OpenAI's official MCP documentation and examples are built with **FastMCP v2**! Check out their [sample MCP server](https://github.com/openai/mcp-server-sample) which demonstrates FastMCP in action.
+</Tip>
+
+## Deep Research
+
+ChatGPT's Deep Research feature requires MCP servers to be internet-accessible HTTP endpoints with **exactly two specific tools**:
+
+- **`search`**: For searching through your resources and returning matching IDs
+- **`fetch`**: For retrieving the full content of specific resources by ID
+
+<Warning>
+If your server doesn't implement both `search` and `fetch` tools with the correct signatures, ChatGPT will show the error: "This MCP server doesn't implement our specification". Both tools are required.
+</Warning>
+
+### Tool Descriptions Matter
+
+Since ChatGPT needs to understand how to use your tools effectively, **write detailed tool descriptions**. The description teaches ChatGPT how to form queries, what parameters to use, and what to expect from your data. Poor descriptions lead to poor search results.
+
+### Create a Server
+
+A Deep Research-compatible server must implement these two required tools:
+
+- **`search(query: str)`** - Takes a query of any kind and returns matching record IDs
+- **`fetch(id: str)`** - Takes an ID and returns the record
+
+**Critical**: Write detailed docstrings for both tools. These descriptions teach ChatGPT how to use your tools effectively. Poor descriptions lead to poor search results.
+
+The `search` tool should take a query (of any kind!) and return IDs. The `fetch` tool should take an ID and return the record.
+
+Here's a reference server implementation you can adapt (see also [OpenAI's sample server](https://github.com/openai/mcp-server-sample) for comparison):
+
+```python server.py [expandable]
+import json
+from pathlib import Path
+from dataclasses import dataclass
+from fastmcp import FastMCP
+
+@dataclass
+class Record:
+    id: str
+    title: str
+    text: str
+    metadata: dict
+
+def create_server(
+    records_path: Path | str,
+    name: str | None = None,
+    instructions: str | None = None,
+) -> FastMCP:
+    """Create a FastMCP server that can search and fetch records from a JSON file."""
+    records = json.loads(Path(records_path).read_text())
+
+    RECORDS = [Record(**r) for r in records]
+    LOOKUP = {r.id: r for r in RECORDS}
+
+    mcp = FastMCP(name=name or "Deep Research MCP", instructions=instructions)
+
+    @mcp.tool()
+    async def search(query: str):
+        """
+        Simple unranked keyword search across title, text, and metadata.
+        Searches for any of the query terms in the record content.
+        Returns a list of matching record IDs for ChatGPT to fetch.
+        """
+        toks = query.lower().split()
+        ids = []
+        for r in RECORDS:
+            record_txt = " ".join(
+                [r.title, r.text, " ".join(r.metadata.values())]
+            ).lower()
+            if any(t in record_txt for t in toks):
+                ids.append(r.id)
+
+        return {"ids": ids}
+
+    @mcp.tool()
+    async def fetch(id: str):
+        """
+        Fetch a record by ID.
+        Returns the complete record data for ChatGPT to analyze and cite.
+        """
+        if id not in LOOKUP:
+            raise ValueError(f"Unknown record ID: {id}")
+        return LOOKUP[id]
+
+    return mcp
+
+if __name__ == "__main__":
+    mcp = create_server("path/to/records.json")
+    mcp.run(transport="streamable-http", port=8000)
+```
+
+### Deploy the Server
+
+Your server must be deployed to a public URL in order for ChatGPT to access it.
+
+For development, you can use tools like `ngrok` to temporarily expose a locally-running server to the internet. We'll do that for this example (you may need to install `ngrok` and create a free account), but you can use any other method to deploy your server.
+
+Assuming you saved the above code as `server.py`, you can run the following two commands in two separate terminals to deploy your server and expose it to the internet:
+
+<CodeGroup>
+```bash FastMCP server
+python server.py
+```
+
+```bash ngrok
+ngrok http 8000
+```
+</CodeGroup>
+
+<Warning>
+This exposes your unauthenticated server to the internet. Only run this command in a safe environment if you understand the risks.
+</Warning>
+
+### Connect to ChatGPT
+
+Replace `https://your-server-url.com` with the actual URL of your server (such as your ngrok URL).
+
+1. Open ChatGPT and go to **Settings** → **Connectors**
+2. Click **Add custom connector**
+3. Enter your server details:
+   - **Name**: Library Catalog
+   - **URL**: Your server URL (e.g., `https://abc123.ngrok.io`)
+   - **Description**: A library catalog for searching and retrieving books
+
+#### Test the Connection
+
+1. Start a new chat in ChatGPT
+2. Click **Tools** → **Run deep research** 
+3. Select your **Library Catalog** connector as a source
+4. Ask questions like:
+   - "Search for Python programming books"
+   - "Find books about AI and machine learning"
+   - "Show me books by the Python Software Foundation"
+
+ChatGPT will use your server's search and fetch tools to find relevant information and cite the sources in its response.
+
+### Troubleshooting
+
+#### "This MCP server doesn't implement our specification"
+
+
+If you get this error, it most likely means that your server doesn't implement the required tools (`search` and `fetch`). To correct it, ensure that your server meets the service requirements.

docs/integrations/claude-code.mdx

@@ -0,0 +1,60 @@
+---
+title: Claude Code + FastMCP
+sidebarTitle: Claude Code
+description: Connect FastMCP servers to Claude Code
+icon: message-smile
+tag: NEW
+---
+
+Claude Code supports MCP servers through multiple transport methods, allowing you to extend Claude's capabilities with custom tools, resources, and prompts from your FastMCP servers.
+
+<Note>
+Claude Code supports both local and remote MCP servers with flexible configuration options. See the [Claude Code MCP documentation](https://docs.anthropic.com/en/docs/claude-code/mcp) for other transport methods.
+</Note>
+
+<Tip>
+Claude Code provides built-in MCP management commands to easily add, configure, and authenticate your FastMCP servers.
+</Tip>
+
+## Create a Server
+
+You can create FastMCP servers using STDIO transport, remote HTTP servers, or local HTTP servers. This example shows one common approach: running an HTTP server locally for development.
+
+```python server.py
+import random
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="Dice Roller")
+
+@mcp.tool
+def roll_dice(n_dice: int) -> list[int]:
+    """Roll `n_dice` 6-sided dice and return the results."""
+    return [random.randint(1, 6) for _ in range(n_dice)]
+
+if __name__ == "__main__":
+    mcp.run(transport="streamable-http", port=8000)
+```
+
+## Connect to Claude Code
+
+Start your server and add it to Claude Code:
+
+```bash
+# Start your server first
+python server.py
+```
+
+Then add it to Claude Code:
+```bash
+claude mcp add dice --transport http http://localhost:8000/mcp/
+```
+
+## Using Your Server
+
+Once connected, Claude Code will automatically discover and use your server's tools when relevant:
+
+```
+Roll some dice for me
+```
+
+Claude will call your `roll_dice` tool and provide the results. If your server provides resources, you can reference them with `@` mentions like `@dice:file://path/to/resource`.

docs/integrations/claude-desktop.mdx

@@ -2,11 +2,15 @@
 title: Claude Desktop + FastMCP
 sidebarTitle: Claude Desktop
 description: Call FastMCP servers from Claude Desktop
-icon: desktop
+icon: message-smile
 ---
 
 
-Claude Desktop supports MCP servers through local STDIO connections, allowing you to extend Claude's capabilities with custom tools, resources, and prompts from your FastMCP servers.
+Claude Desktop supports MCP servers through local STDIO connections and remote servers (beta), allowing you to extend Claude's capabilities with custom tools, resources, and prompts from your FastMCP servers.
+
+<Note>
+Remote MCP server support is currently in beta and available for users on Claude Pro, Max, Team, and Enterprise plans (as of June 2025). Most users will still need to use local STDIO connections.
+</Note>
 
 <Note>
 This guide focuses specifically on using FastMCP servers with Claude Desktop. For general Claude Desktop MCP setup and official examples, see the [official Claude Desktop quickstart guide](https://modelcontextprotocol.io/quickstart/user).
@@ -15,10 +19,10 @@ This guide focuses specifically on using FastMCP servers with Claude Desktop. Fo
 
 ## Requirements
 
-Claude Desktop requires MCP servers to run locally using STDIO transport. This means your server will communicate with Claude through standard input/output rather than HTTP.
+Claude Desktop traditionally requires MCP servers to run locally using STDIO transport, where your server communicates with Claude through standard input/output rather than HTTP. However, users on certain plans now have access to remote server support as well.
 
 <Tip>
-If you need to connect to remote servers, you can create a **proxy server** that runs locally via STDIO and forwards requests to remote HTTP servers. See the [Proxy Servers](#proxy-servers) section below.
+If you don't have access to remote server support or need to connect to remote servers, you can create a **proxy server** that runs locally via STDIO and forwards requests to remote HTTP servers. See the [Proxy Servers](#proxy-servers) section below.
 </Tip>
 
 ## Create a Server
@@ -181,7 +185,7 @@ Claude Desktop runs servers in a completely isolated environment with no access
 ## Remote Servers
 
 
-Claude Desktop only supports local STDIO servers, but FastMCP can create a proxy server that forwards requests to a remote HTTP server. You can install the proxy server in Claude Desktop.
+Users on Claude Pro, Max, Team, and Enterprise plans have first-class remote server support via integrations. For other users, or as an alternative approach, FastMCP can create a proxy server that forwards requests to a remote HTTP server. You can install the proxy server in Claude Desktop.
 
 Create a proxy server that connects to a remote HTTP server:
 

docs/integrations/gemini.mdx

@@ -99,7 +99,7 @@ from fastmcp import Client
 from fastmcp.client.auth import BearerAuth
 
 mcp_client = Client(
-    "https://my-server.com/sse",
+    "https://my-server.com/mcp/",
     auth=BearerAuth("<your-token>"),
 )
 ```

docs/integrations/openai.mdx

@@ -38,7 +38,7 @@ def roll_dice(n_dice: int) -> list[int]:
     return [random.randint(1, 6) for _ in range(n_dice)]
 
 if __name__ == "__main__":
-    mcp.run(transport="sse", port=8000)
+    mcp.run(transport="streamable-http", port=8000)
 ```
 
 ### Deploy the Server
@@ -77,7 +77,7 @@ You'll also need to authenticate with OpenAI. You can do this by setting the `OP
 export OPENAI_API_KEY="your-api-key"
 ```
 
-Here is an example of how to call your server from Python. Note that you'll need to replace `https://your-server-url.com` with the actual URL of your server. In addition, we use `/sse` as the endpoint because we deployed an SSE server with the default path; you may need to use a different endpoint if you customized your server's deployment.
+Here is an example of how to call your server from Python. Note that you'll need to replace `https://your-server-url.com` with the actual URL of your server. In addition, we use `/mcp/` as the endpoint because we deployed a streamable-HTTP server with the default path; you may need to use a different endpoint if you customized your server's deployment.
 
 ```python {4, 11-16}
 from openai import OpenAI
@@ -93,7 +93,7 @@ resp = client.responses.create(
         {
             "type": "mcp",
             "server_label": "dice_server",
-            "server_url": f"{url}/sse",
+            "server_url": f"{url}/mcp/",
             "require_approval": "never",
         },
     ],
@@ -172,7 +172,7 @@ def roll_dice(n_dice: int) -> list[int]:
 
 if __name__ == "__main__":
     print(f"\n---\n\n🔑 Dice Roller access token:\n\n{access_token}\n\n---\n")
-    mcp.run(transport="sse", port=8000)
+    mcp.run(transport="streamable-http", port=8000)
 ```
 
 #### Client Authentication
@@ -212,7 +212,7 @@ resp = client.responses.create(
         {
             "type": "mcp",
             "server_label": "dice_server",
-            "server_url": f"{url}/sse",
+            "server_url": f"{url}/mcp/",
             "require_approval": "never",
             "headers": {
                 "Authorization": f"Bearer {access_token}"