MCP tools

MCP (Model Context Protocol) lets you extend Deep Agents Code with tools from external servers—file systems, APIs, databases, and more—without modifying the agent itself. Deep Agents Code connects to MCP servers at startup, discovers their tools, and makes them available to the agent alongside the built-in tools.

Add MCP servers by adding a .mcp.json config file to your project for project-level scope, or at user-level to apply to all projects.

Paste this prompt into your coding agent to connect the servers, or follow the steps below for Deep Agents Code specifically. For other editors, see Use docs programmatically.

Quickstart

This quickstart adds the LangChain MCP servers to every Deep Agents Code session on your machine. We recommend adding docs-langchain for conceptual guides and how-tos, and reference-langchain for API reference.

Auto-discovery

Deep Agents Code automatically searches for .mcp.json files in standard locations. No flags are needed—just place a config file and it gets picked up.

Discovery locations

Configs are checked in this order (lowest to highest precedence):

The project root is the nearest parent directory containing a .git folder, falling back to the current working directory.

When multiple config files exist, their mcpServers entries are merged by server name. Differently named servers are preserved. If the same server name appears in more than one file, the higher-precedence definition replaces the entire earlier server object; nested fields are not deep-merged. This lets a project-level config override a user-level entry (for example, pinning a different version of the same server) without disturbing your other projects.

Flags

Claude Code compatibility

If you already have a .mcp.json at your project root for Claude Code, Deep Agents Code picks it up automatically—no extra setup needed.

Configuration format

Each key under mcpServers is a server name. The server's fields determine how Deep Agents Code connects to it.

stdio servers (default)

stdio servers are spawned as child processes. Deep Agents Code communicates with them over stdin/stdout.

Approved project servers and servers supplied through --mcp-config start in the session working directory. User-level and plugin servers inherit the backend process directory instead. Set a server's cwd field to override either default.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "env": {}
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "your-token" }
    }
  }
}

SSE and HTTP servers

For remote MCP servers, set type to "sse" or "http" and provide a url:

{
  "mcpServers": {
    "remote-api": {
      "type": "sse",
      "url": "https://api.example.com/mcp",
      "headers": { "Authorization": "Bearer your-token" }
    }
  }
}

Field reference

Environment variable interpolation

String values in command, args, env, url, and headers support ${VAR} references to parent-shell environment variables. Use ${VAR:-default} to provide a value when the variable is unset or empty.

{
    "mcpServers": {
        "work-docs": {
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-filesystem", "${WORK_DOCS_DIR:-/tmp/work-docs}"],
            "env": { "LOG_LEVEL": "${MCP_LOG_LEVEL:-info}" }
        }
    }
}

Multiple servers

You can configure as many servers as you need. Tools from all servers are merged and available to the agent:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_..." }
    },
    "database": {
      "type": "sse",
      "url": "https://db-mcp.internal:8080/mcp",
      "headers": { "Authorization": "Bearer ..." }
    }
  }
}

Set tool-call timeouts

MCP tool calls return an error after 120 seconds by default, so a stalled server does not block the agent indefinitely.

Set [mcp].tool_timeout in ~/.deepagents/config.toml to a number of seconds from 1 through 900. Set DEEPAGENTS_CODE_MCP_TOOL_TIMEOUT to override the user config value. Invalid values fall through to the next configuration source rather than disabling the timeout.

A timeout does not guarantee that the server canceled the operation. Check its state before retrying a tool that changes data: another call can duplicate work.

Tool filtering

Each server may narrow the tools it exposes to the agent with one of two optional fields:

• allowedTools: keep only the listed tools; drop everything else.
• disabledTools: drop the listed tools; keep everything else.

Filtering applies to stdio, HTTP, and SSE servers alike. Both of the following are rejected at config load:

• Setting allowedTools and disabledTools on the same server.
• Setting either field to an empty list (would silently strip every tool, or be a no-op). Omit the field instead.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "allowedTools": ["read_file", "list_directory"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "disabledTools": ["delete_repository", "delete_*_branch"]
    }
  }
}

Match rules

Each entry is a literal tool name or an fnmatch-style glob (any entry containing *, ?, or [ is treated as a pattern). Entries are matched against both the bare MCP tool name and the server-prefixed form ({server}_{tool}), so either form works:

{
  "allowedTools": ["read_file", "fs_list_*"]
}

allowedTools string[]

Tool names or fnmatch glob patterns to keep. All other tools from this server are dropped. Mutually exclusive with disabledTools.

disabledTools string[]

Tool names or fnmatch glob patterns to drop. All other tools from this server are kept. Mutually exclusive with allowedTools.

Read-only tool annotations in Auto mode

MCP servers can attach standard ToolAnnotations when advertising a tool. Deep Agents Code lets a tool bypass classifier review in Auto approval mode only when all of the following are true:

• readOnlyHint is the literal Boolean true.
• destructiveHint is absent, null, or false.
• Every supplied standard hint (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) is a Boolean or null, not a string or another type.

Tools that do not pass this check enter the classifier batch in Auto, use the normal approval UI in Manual, and are rejected in headless runtimes because no approval UI is available. The annotation is a server-provided assertion that Deep Agents Code does not independently verify.

OAuth login

For remote MCP servers that require OAuth (Slack, GitHub, Notion, Linear, and other hosted MCP endpoints), set "auth": "oauth" on the server entry and run the login subcommand once. Tokens are persisted to disk and refreshed automatically.

Configure the server

{
    "mcpServers": {
        "linear": {
            "type": "http",
            "url": "https://mcp.linear.app/mcp",
            "auth": "oauth"
        }
    }
}

auth: "oauth" is mutually exclusive with an Authorization header on the same entry, and cannot be set on a stdio server.

To connect Deep Agents Code to LangSmith, use the LangSmith Remote MCP:

{
    "mcpServers": {
        "langsmith": {
            "url": "https://api.smith.langchain.com/mcp",
            "transport": "http",
            "auth": "oauth"
        }
    }
}

Run the login flow

List configured OAuth servers without stored credentials:

dcode mcp login

Then run the login flow for a server:

dcode mcp login linear

The list uses the same trust-gated configuration as the login flow. It reports servers that have auth: "oauth" but no stored token. It does not check token expiration.

What happens depends on the server's host:

• Spec-compliant servers (the default): Deep Agents Code performs Dynamic Client Registration, opens an Authorization Code + PKCE flow in your browser, and asks you to paste the redirected URL back into the terminal.
• Slack (slack.com, *.slack.com): same paste-back flow, but with Slack's public client preseeded. You are prompted for an optional team ID (e.g., T01234567) so the app installs into the right workspace.
• GitHub (api.githubcopilot.com): RFC 8628 Device Authorization Grant. Deep Agents Code prints a verification URL and a user code; you enter the code in your browser and Deep Agents Code polls for completion.

By default, dcode mcp login reads the same auto-discovered configs Deep Agents Code uses at runtime (subject to project-level trust gating). Pass --mcp-config <path> to use a specific file:

dcode mcp login linear --mcp-config ./mcp-config.json

Token storage

Tokens are written to:

~/.deepagents/.state/mcp-tokens/<server>-<sha256-16(url)>.json

The <sha256-16(url)> segment is the first 16 hex characters of the SHA-256 of the server URL. The directory is locked to mode 0700 and each token file is mode 0600. Files include the OAuth access token, refresh token, and the dynamically registered client info, all in a schema-versioned payload that is written atomically (write-to-temp + rename).

Re-authentication

When refresh fails at runtime (the refresh token expired or was revoked), Deep Agents Code marks the server as unauthenticated instead of crashing the agent. The welcome banner shows the count of unauthenticated servers, and /mcp reports the reason per server. Re-run dcode mcp login <server> to refresh credentials — your conversation continues without restarting.

To re-authenticate an OAuth server without leaving your session, open /mcp, select the server, and press Enter.

Server status

Each configured server lands in one of three states after startup:

A single failing server no longer aborts startup. The agent runs with whichever servers came up cleanly, and the welcome banner surfaces counts of unauthenticated and errored servers next to the tool count. Open /mcp in an interactive session to see per-server status, transport, tool list, and the failure reason for non-ok entries. The viewer live-updates as servers connect and supports tab/shift+tab navigation.

Project-level trust

Project-level configs can contain stdio servers that execute local commands and remote servers whose headers may interpolate ${VAR} from your environment. To prevent untrusted repositories from running arbitrary code or exfiltrating local secrets on CLI startup, Deep Agents Code enforces a default-deny policy for project-level entries.

How it works

• Interactive mode: Deep Agents Code prompts for approval before activating project servers, showing each stdio command and remote URL. Choose Allow once to activate every prompted server for the current session. Choose Allow for this project — until changed to activate every prompted server for the session and select which approvals to save for future sessions.
• Saved approvals: Deep Agents Code writes selected server approvals to the user-level ~/.deepagents/config.toml. Each approval is scoped to the resolved project root, the server name, and a SHA-256 fingerprint of that server definition. If the server command, URL, headers, or other config fields change, Deep Agents Code prompts again.
• Non-interactive mode (-n): Project servers without a matching saved or environment approval are silently skipped unless --trust-project-mcp is passed. Explicit denies still apply.
• Trust covers stdio and remote entries alike: Remote servers can SSRF into localhost or cloud-metadata endpoints during the pre-flight probe and exfiltrate ${VAR} values through headers, so Deep Agents Code gates them the same way as stdio servers.
• User-level configs (~/.deepagents/.mcp.json) are always trusted, following the same trust model as config.toml and hooks.json.
• dcode mcp login also honors project trust: An untrusted project-level config is skipped during login discovery so an attacker-controlled remote entry cannot pull secrets into the OAuth handshake.

Flags

# Skip the approval prompt
dcode --trust-project-mcp

# Non-interactive: explicitly trust project servers
dcode -n "run tests" --trust-project-mcp

Saved approvals

Saved approvals are stored in ~/.deepagents/config.toml:

[mcp]
enabled_project_server_approvals = [
  { project_root = "/Users/you/myproject", name = "docs-langchain", fingerprint = "sha256:abc123..." }
]

To revoke an approval, remove its entry from enabled_project_server_approvals. To force a re-approval without editing config.toml, change the server definition in the project's .mcp.json; the saved fingerprint no longer matches.

The legacy flat [mcp].enabled_project_servers list is ignored in config.toml. Use enabled_project_server_approvals for saved approvals.

Advanced allow and deny policy

Use [mcp].disabled_project_servers in ~/.deepagents/config.toml, or DEEPAGENTS_CODE_DISABLED_PROJECT_MCP_SERVERS in your shell or global ~/.deepagents/.env, to always reject project MCP servers by name. Denies win over saved approvals and over the --trust-project-mcp flag.

The interactive startup prompt also offers session-only denial or permanent denial of selected server names. Permanent denials apply across all projects, unlike project-scoped approvals. To undo a saved denial, remove the name from [mcp].disabled_project_servers in ~/.deepagents/config.toml.

For automation that must pre-approve project MCP servers by name, set DEEPAGENTS_CODE_DANGEROUSLY_ENABLE_PROJECT_MCP_SERVERS in your shell or global ~/.deepagents/.env to a comma-separated list of server names. This is a process-wide escape hatch: A different project, command change, or URL change under the same server name still matches. When this variable is set, Deep Agents Code ignores saved approvals for that process. Prefer saved approvals or --trust-project-mcp unless you need name-based approval across projects and server-definition changes.

deepagents-code>=0.1.40 ignores the former DEEPAGENTS_CODE_ENABLED_PROJECT_MCP_SERVERS variable. Replace it with DEEPAGENTS_CODE_DANGEROUSLY_ENABLE_PROJECT_MCP_SERVERS if you need the same name-based behavior.

System prompt awareness

Connected MCP servers and their tools are automatically listed in the agent's system prompt, grouped by server name and transport type. This helps the model reason about tool provenance and failure domains without requiring manual context.

Troubleshooting

npx -y @modelcontextprotocol/server-filesystem /tmp

Further reading

• LangSmith Remote MCP: connect Deep Agents Code to LangSmith tools over OAuth
• LangChain MCP guide: connecting agents to MCP servers with the MCPAdapter
• MCP specification: the official protocol spec and server registry