Skip to content

Removing !developer_secrets from all docs #496

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 13 commits into from
Sep 16, 2025
Merged

Removing !developer_secrets from all docs #496

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
a2fd842
Update agent-server.mdx
andrew-lastmile Sep 16, 2025
90f7aef
Removing !developer_secrets
andrew-lastmile Sep 16, 2025
5de24f7
Removing !developer_secrets
andrew-lastmile Sep 16, 2025
23993ca
Removing !developer_secrets
andrew-lastmile Sep 16, 2025
ae79927
Removing !developer_secrets
andrew-lastmile Sep 16, 2025
8ae3d91
Removing !developer_secrets
andrew-lastmile Sep 16, 2025
e0d3dfa
Removing !developer_secrets
andrew-lastmile Sep 16, 2025
62e9b10
Removing !developer_secrets
andrew-lastmile Sep 16, 2025
59b9414
Removing !developer_secrets
andrew-lastmile Sep 16, 2025
6b925a2
Removing !developer_secrets
andrew-lastmile Sep 16, 2025
00c1bd8
Removing !developer_secrets
andrew-lastmile Sep 16, 2025
d880ab4
Removing !developer_secrets
andrew-lastmile Sep 16, 2025
968a38f
Update examples/mcp_agent_server/asyncio/README.md
andrew-lastmile Sep 16, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 0 additions & 5 deletions docs/cloud/agent-server.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -147,11 +147,6 @@ uv run mcp-agent serve --app my_agent:app --transport sse
```

#### Deploying to **mcp-agent cloud**
Update your secrets
```yaml mcp_agent.secrets.yaml
openai:
api_key: !developer_secret
```

```bash
uv run mcp-agent login
Expand Down
37 changes: 3 additions & 34 deletions docs/cloud/getting-started.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,18 +60,6 @@ Before you begin, make sure you have:
openai:
default_model: gpt-4o
```

<Note>
Swap your api_key with !developer_secret to mark what keys will be saved as secrets within mcp-agent cloud.
</Note>

```yaml mcp_agent.secrets.yaml
openai:
api_key: !developer_secret
anthropic:
api_key: !developer_secret
# Other secrets as needed
```
</Step>

<Step title="Deploy">
Expand All @@ -83,7 +71,7 @@ Before you begin, make sure you have:

The deployment process will:
1. Check for existing app with this name or create a new one
2. Process your secrets file (transforming `!developer_secret` tags to secure handles)
2. Process your secrets file
3. Bundle and upload your code
4. Deploy to MCP Agent Cloud's managed infrastructure

Expand Down Expand Up @@ -191,11 +179,6 @@ mcp:
openai:
default_model: gpt-4o
```

```yaml mcp_agent.secrets.yaml
openai:
api_key: !developer_secret
```
</CodeGroup>

### Deploy to Cloud
Expand Down Expand Up @@ -335,22 +318,8 @@ MCP_API_KEY="your-key" mcp-agent deploy my-agent
### Secrets Management

MCP Agent Cloud securely handles secrets through the `mcp_agent.secrets.yaml` file:

```yaml mcp_agent.secrets.yaml
openai:
api_key: !developer_secret # Will be stored securely

anthropic:
api_key: !developer_secret

custom_service:
token: !developer_secret
```

During deployment, secrets marked with `!developer_secret` are:
1. Prompted for if not already stored
2. Securely uploaded to MCP Agent Cloud's vault
3. Referenced by handle in the deployed configuration
1. During `mcp-agent deploy`, you will be prompted through the secrets management flow
2. Secrets are safely secured in MCP Agent Cloud

## Testing with MCP Inspector

Expand Down
9 changes: 2 additions & 7 deletions docs/cloud/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,13 +39,6 @@ async def research(query) -> str:
# Tool: "research"
```

4. Mark your secrets that you'd like to safely secure for deployment

```yaml mcp_agent.secrets.yaml
openai:
api_key: !developer_secret
```

## Deploying your mcp-agent app

1. Login into mcp-agent cloud to get your `api key`
Expand All @@ -60,6 +53,8 @@ uv run mcp-agent login
uv run mcp-agent deploy my-first-agent
```

<Note>During the deployment flow, you will be guided through how you'd like your secrets to be managed.</Note>

## Connect to your deployed mcp-agent server

### Claude Desktop integration
Expand Down
11 changes: 0 additions & 11 deletions docs/configuration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -690,17 +690,6 @@ Keep sensitive configuration in separate secrets files:
api_key: "${OPENAI_API_KEY}"
```
</Tab>

<Tab title="Cloud Secrets">
For mcp-agent cloud deployments, use mcp-agent cloud's secret management:

```yaml
openai:
api_key: !developer_secret
```

Mark which secrets you, as the developer, want to keep safe and secure.s
</Tab>
</Tabs>

### Subagent Configuration
Expand Down
16 changes: 4 additions & 12 deletions examples/basic/mcp_basic_agent/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,22 +96,14 @@ uv run main.py
uv run mcp-agent login
```

### `b.` Update your `mcp_agent.secrets.yaml` to mark your developer secrets (keys)

```yaml
openai:
api_key: !developer_secret
anthropic:
api_key: !developer_secret
# Other secrets as needed
```

### `c.` Deploy your agent with a single command
### `b.` Deploy your agent with a single command
```bash
uv run mcp-agent deploy my-first-agent
```

### `d.` Connect to your deployed agent as an MCP server through any MCP client
During deployment, you can select how you would like your secrets managed.

### `c.` Connect to your deployed agent as an MCP server through any MCP client

#### Claude Desktop Integration

Expand Down
16 changes: 4 additions & 12 deletions examples/basic/mcp_model_selector/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,22 +72,14 @@ uv run interactive.py
uv run mcp-agent login
```

### `b.` Update your `mcp_agent.secrets.yaml` to mark your developer secrets (keys)

```yaml
openai:
api_key: !developer_secret
anthropic:
api_key: !developer_secret
# Other secrets as needed
```

### `c.` Deploy your agent with a single command
### `b.` Deploy your agent with a single command
```bash
uv run mcp-agent deploy model-selector-server
```

### `d.` Connect to your deployed agent as an MCP server through any MCP client
During deployment, you can select how you would like your secrets managed.

### `c.` Connect to your deployed agent as an MCP server through any MCP client

#### Claude Desktop Integration

Expand Down
21 changes: 5 additions & 16 deletions examples/mcp_agent_server/asyncio/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -155,38 +155,27 @@ uv run client.py --custom-fastmcp-settings
### [Beta] Deploying to mcp-agent cloud

You can deploy your MCP-Agent app as a hosted mcp-agent app in the Cloud.

1. Update the *mcp_agent.secrets.yaml* file specifying deployed secrets:

```
openai:
api_key: !developer_secret

anthropic:
api_key: !developer_secret
```

2. In your terminal, authenticate into mcp-agent cloud by running:
1. In your terminal, authenticate into mcp-agent cloud by running:
```
uv run mcp-agent login
```

3. You will be redirected to the login page, create an mcp-agent cloud account through Google or Github
2. You will be redirected to the login page, create an mcp-agent cloud account through Google or Github

4. Set up your mcp-agent cloud API Key and copy & paste it into your terminal
3. Set up your mcp-agent cloud API Key and copy & paste it into your terminal

```
andrew_lm@Mac sdk-cloud % uv run mcp-agent login
INFO: Directing to MCP Agent Cloud API login...
Please enter your API key 🔑:
```

5. In your terminal, deploy the MCP app:
4. In your terminal, deploy the MCP app:
```
uv run mcp-agent deploy mcp_agent_server -c /absolute/path/to/your/project
```

6. In the terminal, ou will then be prompted to specify your OpenAI and/or Anthropic keys:
5. In the terminal, you will then be prompted to specify your OpenAI and/or Anthropic keys:

Once the deployment is successful, you should see the following:
```
Comment on lines 155 to 181
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

🧩 Analysis chain

Add a quick self-check to keep MD040 clean going forward.

Run markdownlint locally to verify no remaining MD040 in this file.

🏁 Script executed:

#!/bin/bash
# Verify fenced code blocks have languages
npx -y markdownlint-cli2 'examples/mcp_agent_server/asyncio/README.md' || true
rg -n '```$' examples/mcp_agent_server/asyncio/README.md

Length of output: 6704

Add markdownlint self-check and fix MD040 occurrences

markdownlint-cli2 found 50 errors in examples/mcp_agent_server/asyncio/README.md, including multiple MD040 (fenced code blocks missing language) — e.g. lines 102, 108, 121, 139, 159, 174, 181, 256, 293, 333. Action items:

  • Add language tags to every ``` fence and fix the other lint issues (line-length, list numbering, blank lines).
  • Add a CI or pre-commit check running npx -y markdownlint-cli2 and require no MD040 before merging; re-run the linter until clean.
🧰 Tools
🪛 markdownlint-cli2 (0.17.2)

159-159: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

167-167: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

174-174: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

181-181: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents 
In examples/mcp_agent_server/asyncio/README.md around lines 155 to 181, several
fenced code blocks lack language tags (MD040) and other markdownlint issues
exist; add appropriate language identifiers (bash, sh, or console) to every ```
fence (including at lines 102, 108, 121, 139, 159, 174, 181, etc.), fix other
lint problems such as line-length, list numbering, and required blank lines per
markdownlint rules, and add a CI/pre-commit step that runs npx -y
markdownlint-cli2 (failing on any MD040) so the linter must pass before merging.

Expand Down
23 changes: 3 additions & 20 deletions examples/usecases/mcp_github_to_slack_agent/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,32 +75,15 @@ uv run main.py --owner <github-owner> --repo <repository-name> --channel <slack-
uv run mcp-agent login
```

#### `b.` Update your `mcp_agent.secrets.yaml` to mark your developer secrets (keys)
During deployment, you can select how you would like your secrets managed.

```yaml
$schema: ../../../schema/mcp-agent.config.schema.json

mcp:
servers:
slack:
env:
SLACK_MCP_XOXP_TOKEN: !developer_secret SLACK_MCP_XOXP_TOKEN

github:
headers:
Authorization: !developer_secret GITHUB_PERSONAL_ACCESS_TOKEN_WITH_BEARER_PREFIX

anthropic:
api_key: !developer_secret ANTHROPIC_API_KEY
```

#### `c.` Deploy your agent with a single command
#### `b.` Deploy your agent with a single command

```bash
uv run mcp-agent deploy my-first-agent
```

#### `d.` Connect to your deployed agent as an MCP server through any MCP client
#### `c.` Connect to your deployed agent as an MCP server through any MCP client

##### Claude Desktop Integration

Expand Down
20 changes: 4 additions & 16 deletions examples/workflows/workflow_evaluator_optimizer/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -98,27 +98,15 @@ Deploy your cover letter writer agent to MCP Agent Cloud for remote access and i
uv run mcp-agent login
```

#### `b.` Update your `mcp_agent.secrets.yaml` to mark your developer secrets

Configure your secrets file to mark sensitive keys as developer secrets for secure cloud deployment:

```yaml
$schema: ../../../schema/mcp-agent.config.schema.json

openai:
api_key: !developer_secret OPENAI_API_KEY

anthropic:
api_key: !developer_secret ANTHROPIC_API_KEY
```

#### `c.` Deploy your agent with a single command
#### `b.` Deploy your agent with a single command

```bash
uv run mcp-agent deploy cover-letter-writer
```

#### `d.` Connect to your deployed agent as an MCP server
During deployment, you can select how you would like your secrets managed.

#### `c.` Connect to your deployed agent as an MCP server

Once deployed, you can connect to your agent through various MCP clients:

Expand Down
14 changes: 4 additions & 10 deletions examples/workflows/workflow_intent_classifier/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,20 +60,14 @@ uv run main.py
uv run mcp-agent login
```

### `b.` Update your `mcp_agent.secrets.yaml` to mark your developer secrets (keys)

```yaml
openai:
api_key: !developer_secret
# Other secrets as needed
```

### `c.` Deploy your agent with a single command
### `b.` Deploy your agent with a single command
```bash
uv run mcp-agent deploy workflow-intent-classifier
```

### `d.` Connect to your deployed agent as an MCP server through any MCP client
During deployment, you can select how you would like your secrets managed.

### `c.` Connect to your deployed agent as an MCP server through any MCP client

#### Claude Desktop Integration

Expand Down
16 changes: 4 additions & 12 deletions examples/workflows/workflow_orchestrator_worker/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,22 +76,14 @@ uv run main.py
uv run mcp-agent login
```

### `b.` Update your `mcp_agent.secrets.yaml` to mark your developer secrets (keys)

```yaml
openai:
api_key: !developer_secret
anthropic:
api_key: !developer_secret
# Other secrets as needed
```

### `c.` Deploy your agent with a single command
### `b.` Deploy your agent with a single command
```bash
uv run mcp-agent deploy workflow-orchestrator-server
```

### `d.` Connect to your deployed agent as an MCP server through any MCP client
During deployment, you can select how you would like your secrets managed.

### `c.` Connect to your deployed agent as an MCP server through any MCP client

#### Claude Desktop Integration

Expand Down
2 changes: 1 addition & 1 deletion src/mcp_agent/cli/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ The SDK uses a streamlined approach to secrets management:

Two types of secrets are supported:

1. **Developer Secrets** (`!developer_secret`):
1. **Developer Secrets**:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I didn't see your PR before I did the same. Your's is good, but we should also make some other changes in this README (e.g. see main...fix/update-docs-for-secrets-tags) and should delete src/mcp_agent/cli/SECRETS.md entirely to avoid confusion

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated here -- #497


- Used for secrets that are provided by developers
- Values are known at deployment time
Expand Down
Loading