Skip to content

Commit 17d8ef0

Browse files
jlowinjlowin
authored
Merge pull request jlowin#655 from jlowin/auth-docs
Add docs for server + client auth
2 parents d2ed406 + 091d788 commit 17d8ef0

File tree

13 files changed

+436
-40
lines changed

13 files changed

+436
-40
lines changed

‎docs/clients/auth/bearer.mdx‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
---
2+
title: Bearer Token Authentication
3+
sidebarTitle: Bearer Auth
4+
description: Authenticate your FastMCP client using pre-existing OAuth 2.0 Bearer tokens.
5+
icon: key
6+
---
7+
8+
import { VersionBadge } from "/snippets/version-badge.mdx"
9+
10+
<VersionBadge version="2.6.0" />
11+
12+
<Tip>
13+
Bearer Token authentication is only relevant for HTTP-based transports.
14+
</Tip>
15+
16+
You can configure your FastMCP client to use **bearer authentication** by supplying a valid access token. This is most appropriate for service accounts, long-lived API keys, CI/CD, applications where authentication is managed separately, or other non-interactive authentication methods.
17+
18+
A Bearer token is a JSON Web Token (JWT) that is used to authenticate a request. It is most commonly used in the `Authorization` header of an HTTP request, using the `Bearer` scheme:
19+
20+
```http
21+
Authorization: Bearer <token>
22+
```
23+
24+
25+
## Client Usage
26+
27+
The most straightforward way to use a pre-existing Bearer token is to provide it as a string to the `auth` parameter of the `fastmcp.Client` or transport instance. FastMCP will automatically format it correctly for the `Authorization` header and bearer scheme.
28+
29+
<Tip>
30+
If you're using a string token, do not include the `Bearer` prefix. FastMCP will add it for you.
31+
</Tip>
32+
33+
```python {4}
34+
from fastmcp import Client
35+
36+
async with Client(
37+
"https://fastmcp.cloud/mcp", auth="<your-token>"
38+
) as client:
39+
await client.ping()
40+
```
41+
42+
You can also supply a Bearer token to a transport instance, such as `StreamableHttpTransport` or `SSETransport`:
43+
44+
```python {5}
45+
from fastmcp import Client
46+
from fastmcp.client.transports import StreamableHttpTransport
47+
48+
transport = StreamableHttpTransport(
49+
"http://fastmcp.cloud/mcp", auth="<your-token>"
50+
)
51+
52+
async with Client(transport) as client:
53+
await client.ping()
54+
```
55+
56+
## `BearerAuth` Helper
57+
58+
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.
59+
60+
```python {5}
61+
from fastmcp import Client
62+
from fastmcp.client.auth import BearerAuth
63+
64+
async with Client(
65+
"https://fastmcp.cloud/mcp", auth=BearerAuth(token="<your-token>")
66+
) as client:
67+
await client.ping()
68+
```
69+
70+
## Custom Headers
71+
72+
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:
73+
74+
```python {4}
75+
from fastmcp import Client
76+
77+
async with Client(
78+
"https://fastmcp.cloud/mcp", headers={"X-API-Key": "<your-token>"}
79+
) as client:
80+
await client.ping()
81+
```

‎docs/clients/auth/oauth.mdx‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
---
2+
title: OAuth Authentication
3+
sidebarTitle: OAuth
4+
description: Authenticate your FastMCP client with servers using the OAuth 2.0 Authorization Code Grant, including user interaction via a web browser.
5+
icon: window
6+
---
7+
8+
import { VersionBadge } from "/snippets/version-badge.mdx"
9+
10+
<VersionBadge version="2.6.0" />
11+
12+
<Tip>
13+
OAuth authentication is only relevant for HTTP-based transports and requires user interaction via a web browser.
14+
</Tip>
15+
16+
When your FastMCP client needs to access an MCP server protected by OAuth 2.0, and the process requires user interaction (like logging in and granting consent), you should use the Authorization Code Flow. FastMCP provides the `fastmcp.client.auth.OAuth` helper to simplify this entire process.
17+
18+
This flow is common for user-facing applications where the application acts on behalf of the user.
19+
20+
## Client Usage
21+
22+
23+
### Default Configuration
24+
25+
The simplest way to use OAuth is to pass the string `"oauth"` to the `auth` parameter of the `Client` or transport instance. FastMCP will automatically configure the client to use OAuth with default settings:
26+
27+
```python {4}
28+
from fastmcp import Client
29+
30+
# Uses default OAuth settings
31+
async with Client("https://fastmcp.cloud/mcp", auth="oauth") as client:
32+
await client.ping()
33+
```
34+
35+
36+
### `OAuth` Helper
37+
38+
To fully configure the OAuth flow, use the `OAuth` helper and pass it to the `auth` parameter of the `Client` or transport instance. `OAuth` manages the complexities of the OAuth 2.0 Authorization Code Grant with PKCE (Proof Key for Code Exchange) for enhanced security, and implements the full `httpx.Auth` interface.
39+
40+
```python {2, 4, 6}
41+
from fastmcp import Client
42+
from fastmcp.client.auth import OAuth
43+
44+
oauth = OAuth(mcp_url="https://fastmcp.cloud/mcp")
45+
46+
async with Client("https://fastmcp.cloud/mcp", auth=oauth) as client:
47+
await client.ping()
48+
```
49+
50+
#### `OAuth` Parameters
51+
52+
- **`mcp_url`** (`str`): The full URL of the target MCP server endpoint. Used to discover OAuth server metadata
53+
- **`scopes`** (`str | list[str]`, optional): OAuth scopes to request. Can be space-separated string or list of strings
54+
- **`client_name`** (`str`, optional): Client name for dynamic registration. Defaults to `"FastMCP Client"`
55+
- **`token_storage_cache_dir`** (`Path`, optional): Token cache directory. Defaults to `~/.fastmcp/oauth-mcp-client-cache/`
56+
- **`additional_client_metadata`** (`dict[str, Any]`, optional): Extra metadata for client registration
57+
58+
59+
## OAuth Flow
60+
61+
The OAuth flow is triggered when you use a FastMCP `Client` configured to use OAuth.
62+
63+
<Steps>
64+
<Step title="Token Check">
65+
The client first checks the `token_storage_cache_dir` for existing, valid tokens for the target server. If one is found, it will be used to authenticate the client.
66+
</Step>
67+
<Step title="OAuth Server Discovery">
68+
If no valid tokens exist, the client attempts to discover the OAuth server's endpoints using a well-known URI (e.g., `/.well-known/oauth-authorization-server`) based on the `mcp_url`.
69+
</Step>
70+
<Step title="Dynamic Client Registration">
71+
If the OAuth server supports it and the client isn't already registered (or credentials aren't cached), the client performs dynamic client registration according to RFC 7591.
72+
</Step>
73+
<Step title="Local Callback Server">
74+
A temporary local HTTP server is started on an available port. This server's address (e.g., `http://127.0.0.1:<port>/callback`) acts as the `redirect_uri` for the OAuth flow.
75+
</Step>
76+
<Step title="Browser Interaction">
77+
The user's default web browser is automatically opened, directing them to the OAuth server's authorization endpoint. The user logs in and grants (or denies) the requested `scopes`.
78+
</Step>
79+
<Step title="Authorization Code & Token Exchange">
80+
Upon approval, the OAuth server redirects the user's browser to the local callback server with an `authorization_code`. The client captures this code and exchanges it with the OAuth server's token endpoint for an `access_token` (and often a `refresh_token`) using PKCE for security.
81+
</Step>
82+
<Step title="Token Caching">
83+
The obtained tokens are saved to the `token_storage_cache_dir` for future use, eliminating the need for repeated browser interactions.
84+
</Step>
85+
<Step title="Authenticated Requests">
86+
The access token is automatically included in the `Authorization` header for requests to the MCP server.
87+
</Step>
88+
<Step title="Refresh Token">
89+
If the access token expires, the client will automatically use the refresh token to get a new access token.
90+
</Step>
91+
</Steps>
92+
93+
## Token Management
94+
95+
### Token Storage
96+
97+
OAuth access tokens are automatically cached in `~/.fastmcp/oauth-mcp-client-cache/` and persist between application runs. Files are keyed by the OAuth server's base URL.
98+
99+
### Managing Cache
100+
101+
To clear the tokens for a specific server, instantiate a `FileTokenStorage` instance and call the `clear` method:
102+
103+
```python
104+
from fastmcp.client.auth import FileTokenStorage
105+
106+
storage = FileTokenStorage(server_url="https://fastmcp.cloud/mcp")
107+
await storage.clear()
108+
```
109+
110+
To clear *all* tokens for all servers, call the `clear_all` method on the `FileTokenStorage` class:
111+
112+
```python
113+
from fastmcp.client.auth import FileTokenStorage
114+
115+
FileTokenStorage.clear_all()
116+
```

‎docs/deployment/authentication.mdx‎

Lines changed: 0 additions & 15 deletions
This file was deleted.

‎docs/docs.json‎

Lines changed: 24 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -56,25 +56,39 @@
5656
"servers/context"
5757
]
5858
},
59+
{
60+
"group": "Authentication",
61+
"icon": "shield-check",
62+
"pages": [
63+
"servers/auth/bearer"
64+
]
65+
},
5966
"servers/openapi",
6067
"servers/proxy",
61-
"servers/composition"
62-
]
63-
},
64-
{
65-
"group": "Deployment",
66-
"pages": [
67-
"deployment/running-server",
68-
"deployment/asgi",
69-
"deployment/authentication",
70-
"deployment/cli"
68+
"servers/composition",
69+
{
70+
"group": "Deployment",
71+
"pages": [
72+
"deployment/running-server",
73+
"deployment/asgi",
74+
"deployment/cli"
75+
]
76+
}
7177
]
7278
},
7379
{
7480
"group": "Clients",
7581
"pages": [
7682
"clients/client",
7783
"clients/transports",
84+
{
85+
"group": "Authentication",
86+
"icon": "user-shield",
87+
"pages": [
88+
"clients/auth/bearer",
89+
"clients/auth/oauth"
90+
]
91+
},
7892
"clients/advanced-features"
7993
]
8094
},

0 commit comments

Comments
 (0)