Skip to content

Commit 9aace5e

Browse files
saqadrisaqadri
committed
Cloud docs
1 parent c55e139 commit 9aace5e

17 files changed

+1967
-993
lines changed

‎docs/cloud/getting-started.mdx‎

Lines changed: 45 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -88,7 +88,7 @@ Before you begin, make sure you have:
8888
You'll see output like:
8989
```
9090
App ID: app_abc123xyz
91-
App URL: https://deployments.mcp-agent.com/servers/my-first-agent
91+
App URL: https://<app_id>.deployments.mcp-agent.com
9292
App Status: ONLINE
9393
```
9494
</Step>
@@ -219,7 +219,7 @@ Your agent is now available as an MCP server. Here's how to use it:
219219
First configure the agent (this handles authentication and user secrets):
220220

221221
```bash
222-
mcp-agent cloud configure --id https://deployments.mcp-agent.com/servers/web-summarizer
222+
mcp-agent cloud configure --id https://<app_id>.deployments.mcp-agent.com
223223
```
224224

225225
Then add to your Claude Desktop config (`~/.claude-desktop/config.json`):
@@ -232,7 +232,7 @@ Your agent is now available as an MCP server. Here's how to use it:
232232
"args": [
233233
"-y",
234234
"mcp-remote",
235-
"https://deployments.mcp-agent.com/servers/web-summarizer/sse",
235+
"https://<app_id>.deployments.mcp-agent.com/sse",
236236
"--header",
237237
"Authorization: Bearer <MCP_AGENT_API_KEY>"
238238
]
@@ -245,39 +245,51 @@ Your agent is now available as an MCP server. Here's how to use it:
245245
</Tab>
246246

247247
<Tab title="Python Client">
248-
```python
249-
from mcp_agent.mcp.gen_client import gen_client
250-
251-
async def use_cloud_agent():
252-
# Connect to your cloud agent
253-
async with gen_client("https://deployments.mcp-agent.com/servers/web-summarizer") as server:
254-
# Run the workflow
255-
result = await server.call_tool(
256-
"workflows-WebSummarizerWorkflow-run",
257-
arguments={
258-
"run_parameters": {
259-
"url": "https://www.anthropic.com/research/building-effective-agents"
260-
}
261-
}
262-
)
263-
264-
# Get the run ID
265-
run_id = result.content[0].text
266-
267-
# Check status
268-
status = await server.call_tool(
269-
"workflows-get_status",
270-
arguments={"run_id": run_id}
271-
)
272-
273-
print(f"Summary: {status.content[0].text}")
274-
```
248+
1. Add the deployed server to your config:
249+
250+
```yaml mcp_agent.config.yaml
251+
mcp:
252+
servers:
253+
web_summarizer_cloud:
254+
transport: sse
255+
url: "https://<app_id>.deployments.mcp-agent.com/sse"
256+
headers:
257+
Authorization: "Bearer ${MCP_API_KEY}"
258+
```
259+
260+
2. Call the workflow via the shared registry:
261+
262+
```python
263+
import asyncio
264+
from mcp_agent.config import get_settings
265+
from mcp_agent.mcp.gen_client import gen_client
266+
267+
async def use_cloud_agent():
268+
async with gen_client("web_summarizer_cloud", server_registry=registry) as server:
269+
result = await server.call_tool(
270+
"workflows-WebSummarizerWorkflow-run",
271+
arguments={
272+
"run_parameters": {
273+
"url": "https://www.anthropic.com/research/building-effective-agents"
274+
}
275+
},
276+
)
277+
278+
run_id = result.content[0].text
279+
status = await server.call_tool(
280+
"workflows-get_status",
281+
arguments={"run_id": run_id},
282+
)
283+
print(f"Summary: {status.content[0].text}")
284+
285+
asyncio.run(use_cloud_agent())
286+
```
275287
</Tab>
276288

277289
<Tab title="cURL">
278290
```bash
279291
# Run workflow
280-
curl -X POST https://deployments.mcp-agent.com/servers/web-summarizer/call_tool \
292+
curl -X POST https://<app_id>.deployments.mcp-agent.com/call_tool \
281293
-H "Authorization: Bearer $MCP_AGENT_TOKEN" \
282294
-H "Content-Type: application/json" \
283295
-d '{
@@ -443,10 +455,10 @@ Help users connect to your deployed agent:
443455

444456
```bash
445457
# Configure access for a deployed agent (handles auth and secrets)
446-
mcp-agent cloud configure --id https://deployments.mcp-agent.com/servers/my-agent
458+
mcp-agent cloud configure --id https://<app_id>.deployments.mcp-agent.com
447459

448460
# Show required parameters for configuration
449-
mcp-agent cloud configure --id https://deployments.mcp-agent.com/servers/my-agent --params
461+
mcp-agent cloud configure --id https://<app_id>.deployments.mcp-agent.com --params
450462
```
451463

452464
After configuration, users can connect with their MCP client using the server URL and appropriate transport (SSE or streamable HTTP).

‎docs/deployment/authentication/deployment-auth.mdx‎

Lines changed: 89 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,102 @@
11
---
22
title: Deployment Auth
33
sidebarTitle: "Deployment Auth"
4-
description: "Configure authentication for deployed agents (--no-auth, bearer token, OAuth)"
4+
description: "Configure authentication for deployed MCP servers"
55
icon: key
66
---
77

8-
<Info>
9-
Content on --no-auth flag, bearer token authentication, and OAuth for deployments.
10-
</Info>
8+
Every deployment needs an explicit stance on who can call its tools. This page covers the options supported today and what’s coming next.
119

12-
## Deployment Authentication Options
10+
## 1. Bearer token authentication (default)
1311

14-
- **--no-auth** - Deploy without authentication (development only)
15-
- **Bearer Token** - Simple token-based authentication
16-
- **OAuth** - Full OAuth 2.1 authentication flows
12+
- Each user runs `mcp-agent login` to obtain an API key (`lm_mcp_api_*`).
13+
- Keys are stored locally (`~/.config/mcp-agent/credentials.json`) and can also be provided via the `MCP_API_KEY` environment variable (CI, containers).
14+
- Clients include the key in the `Authorization: Bearer <token>` header.
15+
- Deployments validate the token before executing requests.
16+
17+
### Share instructions with users
18+
19+
```
20+
1. Install mcp-agent (uv tool install mcp-agent)
21+
2. Run mcp-agent login and follow the browser prompts
22+
3. Configure the client (mcp-agent install ... --client claude_desktop)
23+
```
24+
25+
### Rotate or revoke
26+
27+
- Re-run `mcp-agent login` to issue a new key (old keys will stop working).
28+
- Delete the key file to force re-authentication.
29+
- Per-user revocation UI is on the roadmap; in the interim contact support if a key is compromised.
30+
31+
### CLI recap
1732

1833
```bash
19-
# Deploy with OAuth
20-
mcp-agent deploy my-agent --auth oauth
34+
mcp-agent login # browser flow
35+
mcp-agent cloud auth whoami # confirm identity
36+
mcp-agent install <url> --client cursor # writes config with Authorization header
37+
```
38+
39+
## 2. Unauthenticated access (`--no-auth`)
2140

22-
# Deploy with bearer token
23-
mcp-agent deploy my-agent --auth bearer
41+
Use this mode for public servers, demos, or ChatGPT Apps (which cannot provide custom headers).
2442

25-
# Deploy without auth (not recommended)
26-
mcp-agent deploy my-agent --no-auth
43+
```bash
44+
mcp-agent deploy blog-tools --no-auth
2745
```
46+
47+
- Anyone with the server URL can call it.
48+
- Logs still capture caller metadata (IP, user agent) for monitoring.
49+
- You can re-enable auth later:
50+
51+
```bash
52+
mcp-agent deploy blog-tools --auth
53+
```
54+
55+
(`--auth` toggles `unauthenticatedAccess` back to false.)
56+
57+
> For apps deployed without auth, consider rate limiting or requiring custom user-provided secrets to avoid abuse.
58+
59+
## 3. OAuth 2.1 (coming soon, preview)
60+
61+
The upcoming release implements the MCP OAuth specification across three surfaces:
62+
63+
1. **Authorization server** (control plane)
64+
- Metadata endpoint: `/.well-known/oauth-authorization-server`
65+
- Supports Google + GitHub providers initially
66+
- Issues access & refresh tokens
67+
2. **Resource server** (your deployment)
68+
- Implements `/.well-known/oauth-protected-resource` (RFC 9728)
69+
- Validates JWTs or proxies to token introspection
70+
- Allows per-scope access control (e.g., `read`, `write`, `admin`)
71+
3. **Client tooling**
72+
- `mcp-agent install` and `mcp-agent cloud configure` will drive the auth flow for supported clients (browser-based loopback or device code).
73+
74+
Keep an eye on release notes for timelines. The migration will be additive—existing bearer-token flows continue to work.
75+
76+
## 4. Combining with secrets management
77+
78+
- Store long-lived service credentials in `mcp_agent.secrets.yaml` as deployment secrets; the runtime injects them securely.
79+
- Ask end-users for their own credentials via `mcp-agent cloud configure` (user secrets). You can enforce domain restrictions or other policies in code when processing those secrets.
80+
81+
## 5. Security best practices
82+
83+
<AccordionGroup>
84+
<Accordion title="Least privilege">
85+
Only expose tools/resources that need to be public. For internal deployments, keep `--auth` enabled and share API keys via secure channels.
86+
</Accordion>
87+
<Accordion title="Audit logs">
88+
The platform records every API call (user, timestamp, tool, outcome). A user-facing audit surface is planned—ask the team if you need access before it ships.
89+
</Accordion>
90+
<Accordion title="Secret rotation">
91+
Rotate provider API keys regularly. Redeploy with updated secrets; the CLI invalidates old handles automatically.
92+
</Accordion>
93+
<Accordion title="Client distribution">
94+
Provide install scripts (`mcp-agent install`) rather than asking users to edit config files manually. This reduces the risk of misconfigured auth headers.
95+
</Accordion>
96+
</AccordionGroup>
97+
98+
## References
99+
100+
- [Authentication overview →](/deployment/authentication/overview)
101+
- [External MCP server auth (downstream credentials) →](/deployment/authentication/external-mcp-auth)
102+
- [Secrets management →](/deployment/mcp-agent-cloud/manage-secrets)

‎docs/deployment/authentication/external-mcp-auth.mdx‎

Lines changed: 116 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,125 @@
11
---
22
title: External MCP Auth
33
sidebarTitle: "External MCP Auth"
4-
description: "Authentication for external MCP servers"
4+
description: "Configure your agent to authenticate when calling downstream MCP servers"
55
icon: link
66
---
77

8-
<Info>
9-
Link to MCP Server Authentication section.
10-
</Info>
8+
Many agents call other MCP servers (e.g., Linear, GitHub, Slack). Each downstream server may require API keys or OAuth credentials. Use `mcp_agent.config.yaml` to specify how your agent should authenticate when acting as an MCP client.
119

12-
## External MCP Server Authentication
10+
## API key (static) authentication
1311

14-
When your agents connect to external MCP servers that require authentication, configure auth in your application.
12+
```yaml mcp_agent.config.yaml
13+
mcp:
14+
servers:
15+
github:
16+
command: "uvx"
17+
args: ["mcp-server-github"]
18+
auth:
19+
api_key: "${GITHUB_TOKEN}" # injected from secrets
20+
```
1521
16-
[See MCP Server Authentication →](/mcp-agent-sdk/mcp/server-authentication)
22+
- Store the actual token in `mcp_agent.secrets.yaml` (deployment secret) or `mcp_agent.configured.secrets.yaml` (user secret).
23+
- At runtime, `ServerRegistry` injects the `Authorization` header when connecting to the MCP server.
24+
- Supports any header name via `auth.headers` if the server expects a custom format.
25+
26+
## OAuth client credentials / authorization code
27+
28+
For MCP servers that implement OAuth (Linear, Notion, custom internal IdPs), configure the `oauth` block:
29+
30+
```yaml
31+
mcp:
32+
servers:
33+
notion:
34+
command: "uvx"
35+
args: ["mcp-server-notion"]
36+
auth:
37+
oauth:
38+
enabled: true
39+
authorization_server: "https://auth.notion.com"
40+
client_id: "${NOTION_CLIENT_ID}"
41+
client_secret: "${NOTION_CLIENT_SECRET}"
42+
scopes: ["documents.read", "documents.write"]
43+
resource: "https://mcp.notion.com"
44+
redirect_uri_options:
45+
- "http://127.0.0.1:33418/callback"
46+
- "https://<app_id>.deployments.mcp-agent.com/oauth/callback"
47+
```
48+
49+
How it works:
50+
51+
1. When the agent first needs the server, the OAuth manager checks the token store.
52+
2. If no token exists, it launches an authorization flow (internal callback inside the deployment or local loopback while running locally).
53+
3. Access + refresh tokens are stored in the configured token store (memory or Redis).
54+
4. Tokens are refreshed automatically before expiry (`refresh_leeway_seconds`).
55+
56+
### Token store configuration
57+
58+
```yaml
59+
oauth:
60+
token_store:
61+
backend: "redis"
62+
redis_url: "${REDIS_URL}"
63+
redis_prefix: "mcp_agent:oauth_tokens"
64+
```
65+
66+
- `memory` (default) – in-memory, process-scoped. Great for development but not shared across workers.
67+
- `redis` – recommended for cloud deployments if your app uses multiple processes or needs persistence across restarts.
68+
69+
## Seeding tokens manually
70+
71+
If you already have an access token:
72+
73+
```yaml
74+
mcp:
75+
servers:
76+
linear:
77+
auth:
78+
oauth:
79+
enabled: true
80+
access_token: "${LINEAR_ACCESS_TOKEN}"
81+
refresh_token: "${LINEAR_REFRESH_TOKEN}"
82+
expires_at: 1740694445
83+
```
84+
85+
This bypasses the interactive flow; the token manager will refresh using the provided refresh token when needed.
86+
87+
## Request-time headers
88+
89+
For bespoke auth schemes, you can specify arbitrary headers or environment variables:
90+
91+
```yaml
92+
mcp:
93+
servers:
94+
internal_search:
95+
command: "./bin/internal-search"
96+
env:
97+
SEARCH_API_KEY: "${SEARCH_API_KEY}"
98+
auth:
99+
headers:
100+
X-Org: "lastmile"
101+
Authorization: "Bearer ${SEARCH_API_KEY}"
102+
```
103+
104+
## Best practices
105+
106+
<AccordionGroup>
107+
<Accordion title="Keep secrets out of code">
108+
Always reference `${ENV_VAR}` placeholders in config and store the actual values in secrets files. Never hardcode tokens in Python modules.
109+
</Accordion>
110+
<Accordion title="Differentiate developer vs user secrets">
111+
If every user needs their own credential (e.g., personal GitHub PAT), mark it as `!user_secret` so `mcp-agent cloud configure` collects it when they onboard the app.
112+
</Accordion>
113+
<Accordion title="Token sharing">
114+
For OAuth-protected upstream servers you probably want a shared token cache (Redis) to avoid re-authorizing for every workflow run.
115+
</Accordion>
116+
<Accordion title="Handle scope failures">
117+
Downstream servers may reject requests if scopes are missing. Log the response body and expose a clear error so users know to re-run the configure flow.
118+
</Accordion>
119+
</AccordionGroup>
120+
121+
## Related docs
122+
123+
- [Secrets management →](/deployment/mcp-agent-cloud/manage-secrets)
124+
- [Authentication overview →](/deployment/authentication/overview)
125+
- [MCP server configuration reference →](/reference/configuration#mcp-servers)

0 commit comments

Comments
 (0)