Merge pull request #674 from jlowin/anthropic

Add Anthropic + Claude desktop integration guides

docs/clients/auth/bearer.mdx

@@ -30,23 +30,25 @@ The most straightforward way to use a pre-existing Bearer token is to provide it
 If you're using a string token, do not include the `Bearer` prefix. FastMCP will add it for you.
 </Tip>
 
-```python {4}
+```python {5}
 from fastmcp import Client
 
 async with Client(
-    "https://fastmcp.cloud/mcp", auth="<your-token>"
+    "https://fastmcp.cloud/mcp", 
+    auth="<your-token>",
 ) as client:
     await client.ping()
 ```
 
 You can also supply a Bearer token to a transport instance, such as `StreamableHttpTransport` or `SSETransport`:
 
-```python {5}
+```python {6}
 from fastmcp import Client
 from fastmcp.client.transports import StreamableHttpTransport
 
 transport = StreamableHttpTransport(
-    "http://fastmcp.cloud/mcp", auth="<your-token>"
+    "http://fastmcp.cloud/mcp", 
+    auth="<your-token>",
 )
 
 async with Client(transport) as client:
@@ -57,12 +59,13 @@ async with Client(transport) as client:
 
 If you prefer to be more explicit and not rely on FastMCP to transform your string token, you can use the `BearerAuth` class yourself, which implements the `httpx.Auth` interface.
 
-```python {5}
+```python {6}
 from fastmcp import Client
 from fastmcp.client.auth import BearerAuth
 
 async with Client(
-    "https://fastmcp.cloud/mcp", auth=BearerAuth(token="<your-token>")
+    "https://fastmcp.cloud/mcp", 
+    auth=BearerAuth(token="<your-token>"),
 ) as client:
     await client.ping()
 ```
@@ -71,11 +74,12 @@ async with Client(
 
 If the MCP server expects a custom header or token scheme, you can manually set the client's `headers` instead of using the `auth` parameter:
 
-```python {4}
+```python {5}
 from fastmcp import Client
 
 async with Client(
-    "https://fastmcp.cloud/mcp", headers={"X-API-Key": "<your-token>"}
+    "https://fastmcp.cloud/mcp", 
+    headers={"X-API-Key": "<your-token>"},
 ) as client:
     await client.ping()
 ```

docs/docs.json

@@ -71,8 +71,7 @@
                         "icon": "upload",
                         "pages": [
                             "deployment/running-server",
-                            "deployment/asgi",
-                            "deployment/cli"
+                            "deployment/asgi"
                         ]
                     }
                 ]
@@ -96,6 +95,8 @@
             {
                 "group": "Integrations",
                 "pages": [
+                    "integrations/anthropic",
+                    "integrations/claude-desktop",
                     "integrations/openai",
                     "integrations/contrib"
                 ]
@@ -105,7 +106,8 @@
                 "pages": [
                     "patterns/decorating-methods",
                     "patterns/http-requests",
-                    "patterns/testing"
+                    "patterns/testing",
+                    "patterns/cli"
                 ]
             }
         ]

docs/integrations/anthropic.mdx

@@ -0,0 +1,225 @@
+---
+title: Anthropic
+sidebarTitle: Anthropic
+description: Access FastMCP servers from the Anthropic Messages API
+icon: message-smile
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+Anthropic supports MCP servers through the [MCP connector](https://docs.anthropic.com/en/docs/agents-and-tools/mcp-connector) feature in the Messages API, allowing you to extend AI capabilities with custom tools from remote MCP servers.
+
+## Messages API
+
+Anthropic's [Messages API](https://docs.anthropic.com/en/api/messages) supports MCP servers as remote tool sources. This tutorial will show you how to create a FastMCP server and deploy it to a public URL, then how to call it from the Messages API.
+
+<Tip>
+Currently, the MCP connector only accesses **tools** from MCP servers—it queries the `list_tools` endpoint and exposes those functions to Claude. Other MCP features like resources and prompts are not currently supported. You can read more about the MCP connector in the [Anthropic documentation](https://docs.anthropic.com/en/docs/agents-and-tools/mcp-connector).
+</Tip>
+
+### Create a Server
+
+First, create a FastMCP server with the tools you want to expose. For this example, we'll create a server with a single tool that rolls dice.
+
+```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="sse", port=8000)
+```
+
+### Deploy the Server
+
+Your server must be deployed to a public URL in order for Anthropic to access it. The MCP connector supports both SSE and Streamable HTTP transports.
+
+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>
+
+### Call the Server
+
+To use the Messages API with MCP servers, you'll need to install the Anthropic Python SDK (not included with FastMCP):
+
+```bash
+pip install anthropic
+```
+
+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.**
+
+```python {5, 13-22}
+import anthropic
+from rich import print
+
+# Your server URL (replace with your actual URL)
+url = 'https://your-server-url.com'
+
+client = anthropic.Anthropic()
+
+response = client.beta.messages.create(
+    model="claude-sonnet-4-20250514",
+    max_tokens=1000,
+    messages=[{"role": "user", "content": "Roll a few dice!"}],
+    mcp_servers=[
+        {
+            "type": "url",
+            "url": f"{url}/sse",
+            "name": "dice-server",
+        }
+    ],
+    extra_headers={
+        "anthropic-beta": "mcp-client-2025-04-04"
+    }
+)
+
+print(response.content)
+```
+
+If you run this code, you'll see something like the following output:
+
+```text
+I'll roll some dice for you! Let me use the dice rolling tool.
+
+I rolled 3 dice and got: 4, 2, 6
+
+The results were 4, 2, and 6. Would you like me to roll again or roll a different number of dice?
+```
+
+
+### Authentication
+
+<VersionBadge version="2.6.0" />
+
+The MCP connector supports OAuth authentication through authorization tokens, which means you can secure your server while still allowing Anthropic to access it.
+
+#### Server Authentication
+
+The simplest way to add authentication to the server is to use a bearer token scheme. 
+
+For this example, we'll quickly generate our own tokens with FastMCP's `RSAKeyPair` utility, but this may not be appropriate for production use. For more details, see the complete server-side [Bearer Auth](/servers/auth/bearer) documentation. 
+
+We'll start by creating an RSA key pair to sign and verify tokens.
+
+```python
+from fastmcp.server.auth.providers.bearer import RSAKeyPair
+
+key_pair = RSAKeyPair.generate()
+access_token = key_pair.create_token(audience="dice-server")
+```
+
+<Warning>
+FastMCP's `RSAKeyPair` utility is for development and testing only.
+</Warning> 
+
+Next, we'll create a `BearerAuthProvider` to authenticate the server. 
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth import BearerAuthProvider
+
+auth = BearerAuthProvider(
+    public_key=key_pair.public_key,
+    audience="dice-server",
+)
+
+mcp = FastMCP(name="Dice Roller", auth=auth)
+```
+
+Here is a complete example that you can copy/paste. For simplicity and the purposes of this example only, it will print the token to the console. **Do NOT do this in production!**
+
+```python server.py [expandable]
+from fastmcp import FastMCP
+from fastmcp.server.auth import BearerAuthProvider
+from fastmcp.server.auth.providers.bearer import RSAKeyPair
+import random
+
+key_pair = RSAKeyPair.generate()
+access_token = key_pair.create_token(audience="dice-server")
+
+auth = BearerAuthProvider(
+    public_key=key_pair.public_key,
+    audience="dice-server",
+)
+
+mcp = FastMCP(name="Dice Roller", auth=auth)
+
+@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__":
+    print(f"\n---\n\n🔑 Dice Roller access token:\n\n{access_token}\n\n---\n")
+    mcp.run(transport="sse", port=8000)
+```
+
+#### Client Authentication
+
+If you try to call the authenticated server with the same Anthropic code we wrote earlier, you'll get an error indicating that the server rejected the request because it's not authenticated.
+
+```python
+Error code: 400 - {
+    "type": "error", 
+    "error": {
+        "type": "invalid_request_error", 
+        "message": "MCP server 'dice-server' requires authentication. Please provide an authorization_token.",
+    },
+}
+```
+
+To authenticate the client, you can pass the token using the `authorization_token` parameter in your MCP server configuration:
+
+```python {8, 21}
+import anthropic
+from rich import print
+
+# Your server URL (replace with your actual URL)
+url = 'https://your-server-url.com'
+
+# Your access token (replace with your actual token)
+access_token = 'your-access-token'
+
+client = anthropic.Anthropic()
+
+response = client.beta.messages.create(
+    model="claude-sonnet-4-20250514",
+    max_tokens=1000,
+    messages=[{"role": "user", "content": "Roll a few dice!"}],
+    mcp_servers=[
+        {
+            "type": "url",
+            "url": f"{url}/sse",
+            "name": "dice-server",
+            "authorization_token": access_token
+        }
+    ],
+    extra_headers={
+        "anthropic-beta": "mcp-client-2025-04-04"
+    }
+)
+
+print(response.content)
+```
+
+You should now see the dice roll results in the output.

docs/integrations/claude-desktop.mdx

@@ -0,0 +1,221 @@
+---
+title: Claude Desktop
+sidebarTitle: Claude Desktop
+description: Integrate FastMCP servers with Claude Desktop
+icon: desktop
+---
+
+
+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.
+
+<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).
+</Note>
+
+
+## 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.
+
+<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.
+</Tip>
+
+## Create a Server
+
+The examples in this guide will use the following simple dice-rolling server, saved as `server.py`.
+
+```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()
+```
+
+## Install the Server
+
+### FastMCP CLI
+
+The easiest way to install a FastMCP server in Claude Desktop is using the `fastmcp install` command. This automatically handles the configuration and dependency management.
+
+```bash
+fastmcp install server.py
+```
+
+The install command supports the same `file.py:object` notation as the `run` command. If no object is specified, it will automatically look for a FastMCP server object named `mcp`, `server`, or `app` in your file:
+
+```bash
+# These are equivalent if your server object is named 'mcp'
+fastmcp install server.py
+fastmcp install server.py:mcp
+
+# Use explicit object name if your server has a different name
+fastmcp install server.py:my_custom_server
+```
+
+After installation, restart Claude Desktop completely. You should see a hammer icon (🔨) in the bottom left of the input box, indicating that MCP tools are available.
+
+#### Dependencies
+
+If your server has dependencies, include them with the `--with` flag:
+
+```bash
+fastmcp install server.py --with pandas --with requests
+```
+
+Alternatively, you can specify dependencies directly in your server code:
+
+```python server.py
+from fastmcp import FastMCP
+
+mcp = FastMCP(
+    name="Dice Roller",
+    dependencies=["pandas", "requests"]
+)
+```
+
+#### Environment Variables
+
+<Warning>
+Claude Desktop runs servers in a completely isolated environment with no access to your shell environment or locally installed applications. You must explicitly pass any environment variables your server needs.
+</Warning>
+
+If your server needs environment variables (like API keys), you must include them:
+
+```bash
+fastmcp install server.py --name "Weather Server" \
+  --env-var API_KEY=your-api-key \
+  --env-var DEBUG=true
+```
+
+Or load them from a `.env` file:
+
+```bash
+fastmcp install server.py --name "Weather Server" --env-file .env
+```
+<Warning>
+- **`uv` must be installed and available in your system PATH**. Claude Desktop runs in its own isolated environment and needs `uv` to manage dependencies.
+- **On macOS, it is recommended to install `uv` globally with Homebrew** so that Claude Desktop will detect it: `brew install uv`. Installing `uv` with other methods may not make it accessible to Claude Desktop.
+</Warning>
+
+
+### Manual Configuration
+
+For more control over the configuration, you can manually edit Claude Desktop's configuration file. You can open the configuration file from Claude's developer settings, or find it in the following locations:
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+The configuration file is a JSON object with a `mcpServers` key, which contains the configuration for each MCP server.
+
+```json
+{
+  "mcpServers": {
+    "dice-roller": {
+      "command": "python",
+      "args": ["path/to/your/server.py"]
+    }
+  }
+}
+```
+
+After updating the configuration file, restart Claude Desktop completely. Look for the hammer icon (🔨) to confirm your server is loaded.
+
+#### Dependencies
+
+If your server has dependencies, you can use `uv` or another package manager to set up the environment.
+
+
+```json
+{
+  "mcpServers": {
+    "dice-roller": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--with", "pandas",
+        "--with", "requests", 
+        "python",
+        "path/to/your/server.py"
+      ]
+    }
+  }
+}
+```
+
+<Warning>
+- **`uv` must be installed and available in your system PATH**. Claude Desktop runs in its own isolated environment and needs `uv` to manage dependencies.
+- **On macOS, it is recommended to install `uv` globally with Homebrew** so that Claude Desktop will detect it: `brew install uv`. Installing `uv` with other methods may not make it accessible to Claude Desktop.
+</Warning>
+
+#### Environment Variables
+
+You can also specify environment variables in the configuration:
+
+```json
+{
+  "mcpServers": {
+    "weather-server": {
+      "command": "python",
+      "args": ["path/to/weather_server.py"],
+      "env": {
+        "API_KEY": "your-api-key",
+        "DEBUG": "true"
+      }
+    }
+  }
+}
+```
+<Warning>
+Claude Desktop runs servers in a completely isolated environment with no access to your shell environment or locally installed applications. You must explicitly pass any environment variables your server needs.
+</Warning>
+
+
+## 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.
+
+Create a proxy server that connects to a remote HTTP server:
+
+```python proxy_server.py
+from fastmcp import FastMCP
+
+# Create a proxy to a remote server
+proxy = FastMCP.as_proxy(
+    "https://example.com/mcp/sse", 
+    name="Remote Server Proxy"
+)
+
+if __name__ == "__main__":
+    proxy.run()  # Runs via STDIO for Claude Desktop
+```
+
+### Authentication
+
+For authenticated remote servers, create an authenticated client following the guidance in the [client auth documentation](/clients/auth/bearer) and pass it to the proxy:
+
+```python auth_proxy_server.py {7}
+from fastmcp import FastMCP, Client
+from fastmcp.client.auth import BearerAuth
+
+# Create authenticated client
+client = Client(
+    "https://api.example.com/mcp/sse",
+    auth=BearerAuth(token="your-access-token")
+)
+
+# Create proxy using the authenticated client
+proxy = FastMCP.as_proxy(client, name="Authenticated Proxy")
+
+if __name__ == "__main__":
+    proxy.run()
+```
+

docs/integrations/openai.mdx

@@ -1,7 +1,7 @@
 ---
 title: OpenAI
 sidebarTitle: OpenAI
-description: Integrate FastMCP servers with the OpenAI API
+description: Access FastMCP servers from the OpenAI API
 icon: message-smile
 ---
 
@@ -123,7 +123,9 @@ key_pair = RSAKeyPair.generate()
 access_token = key_pair.create_token(audience="dice-server")
 ```
 
-This will generate a new RSA key pair and a corresponding access token.
+<Warning>
+FastMCP's `RSAKeyPair` utility is for development and testing only.
+</Warning> 
 
 Next, we'll create a `BearerAuthProvider` to authenticate the server. 
 

docs/{deployment → patterns}/cli.mdx

@@ -148,8 +148,8 @@ Install a MCP server in the Claude desktop app.
 fastmcp install server.py
 ```
 
-
 Note that for security reasons, Claude runs every MCP server in a completely isolated environment. Therefore, all dependencies must be explicitly specified using the `--with` and/or `--with-editable` options (following `uv` conventions) or by attaching them to your server in code via the `dependencies` parameter.
+
 <Warning>
 - **`uv` must be installed and available in your system PATH**. Claude Desktop runs in its own isolated environment and needs `uv` to manage dependencies.
 - **On macOS, it is recommended to install `uv` globally with Homebrew** so that Claude Desktop will detect it: `brew install uv`. Installing `uv` with other methods may not make it accessible to Claude Desktop.
@@ -159,21 +159,24 @@ Note that for security reasons, Claude runs every MCP server in a completely iso
 The `install` command currently only sets up servers for STDIO transport. When installed in the Claude desktop app, your server will be run using STDIO regardless of any transport configuration in your code.
 </Warning>
 
-#### Options
+#### Server Specification
 
-| Option | Flag | Description |
-| ------ | ---- | ----------- |
-| Server Name | `--name`, `-n` | Custom name for the server |
-| Editable Package | `--with-editable`, `-e` | Directory containing pyproject.toml to install in editable mode |
-| Additional Packages | `--with` | Additional packages to install (can be used multiple times) |
-| Environment Variables | `--env-var`, `-v` | Environment variables in KEY=VALUE format (can be used multiple times) |
-| Environment File | `--env-file`, `-f` | Load environment variables from a .env file |
+The `install` command supports the same `file.py:object` notation as the `run` command:
 
-**Example**
+1. `server.py` - imports the module and looks for a FastMCP object named `mcp`, `server`, or `app`. Errors if no such object is found.
+2. `server.py:custom_name` - imports and uses the specified server object
+
+**Examples**
 
 ```bash
-# Install server with custom name, dependencies, and environment variables
-fastmcp install server.py -n "My Analysis Server" -e . --with pandas --env-var API_KEY=12345
+# Auto-detects server object (looks for 'mcp', 'server', or 'app')
+fastmcp install server.py
+
+# Uses specific server object
+fastmcp install server.py:my_server
+
+# With custom name and dependencies
+fastmcp install server.py:my_server -n "My Analysis Server" --with pandas
 ```
 
 ### `version`

server.py

@@ -0,0 +1,26 @@
+import random
+
+from fastmcp import FastMCP
+from fastmcp.server.auth import BearerAuthProvider
+from fastmcp.server.auth.providers.bearer import RSAKeyPair
+
+key_pair = RSAKeyPair.generate()
+access_token = key_pair.create_token(audience="dice-server")
+
+auth = BearerAuthProvider(
+    public_key=key_pair.public_key,
+    audience="dice-server",
+)
+
+mcp = FastMCP(name="Dice Roller", auth=auth)
+
+
+@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__":
+    print(f"\n---\n\n🔑 Dice Roller access token:\n\n{access_token}\n\n---\n")
+    mcp.run(transport="sse", port=8000)