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

​
Quickstart

Create a config file

Create a .mcp.json file at your project root. The format follows the Claude Desktop convention:
.mcp.json
{
    "mcpServers": {
        "docs-langchain": {
        "type": "http",
        "url": "https://docs.langchain.com/mcp"
        }
    }
}

Launch the CLI

deepagents
On startup, the CLI automatically discovers your .mcp.json, spawns each configured server, discovers its tools, and prints a confirmation:
✓ Loaded 3 MCP tools
The agent can now use those tools for the duration of the session. Sessions are kept alive — stdio servers are not restarted between tool calls.

​
Auto-discovery

The CLI 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):
PriorityLocationScope
1 (lowest)~/.deepagents/.mcp.jsonUser-level — applies to all projects
2<project>/.deepagents/.mcp.jsonProject-level — .deepagents subdirectory
3 (highest)<project>/.mcp.jsonProject-level — root (Claude Code compatible)
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. If the same server name appears in more than one file, the higher-precedence config wins.

​
Flags

FlagBehavior
--mcp-config PATHAdd an explicit config as the highest-precedence source (merged on top of auto-discovered configs)
--no-mcpDisable MCP entirely — no servers are loaded
--mcp-config and --no-mcp are mutually exclusive.

​
Claude Code compatibility

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

​
Configuration format

Each key under mcpServers is a server name. The server’s fields determine how the CLI connects to it.

​
stdio servers (default)

stdio servers are spawned as child processes. The CLI communicates with them over stdin/stdout.
mcp-config.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "env": {}
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "your-token" }
    }
  }
}
​
command
string
required
The executable to run.
​
args
string[]
Arguments passed to the command.
​
env
object
Environment variables set for the subprocess. Use this to pass API keys and other credentials without exposing them in shell history.

​
SSE and HTTP servers

For remote MCP servers, set type to "sse" or "http" and provide a url:
mcp-config.json
{
  "mcpServers": {
    "remote-api": {
      "type": "sse",
      "url": "https://api.example.com/mcp",
      "headers": { "Authorization": "Bearer your-token" }
    }
  }
}
​
type
string
required
Transport type: "sse" for Server-Sent Events or "http" for streamable HTTP.
​
url
string
required
The server endpoint URL.
​
headers
object
HTTP headers sent with every request. Commonly used for authentication.

​
Server types summary

TypeRequired fieldsOptional fields
stdio (default)commandargs, env
ssetype: "sse", urlheaders
httptype: "http", urlheaders
The type field can also be written as transport for compatibility with other MCP clients.

​
Multiple servers

You can configure as many servers as you need. Tools from all servers are merged and available to the agent:
mcp-config.json
{
  "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 ..." }
    }
  }
}

​
Project-level trust

Project-level configs can contain stdio servers that execute local commands. To prevent untrusted repositories from running arbitrary code on CLI startup, the CLI enforces a default-deny policy for project-level stdio servers.

​
How it works

  • Interactive mode: The CLI prompts for approval before launching project stdio servers, showing the exact commands. Approval is persisted using a SHA-256 content fingerprint — if the config changes, you are prompted again.
  • Non-interactive mode (-n): Project stdio servers are silently skipped unless --trust-project-mcp is passed.
  • Remote servers (SSE/HTTP) from project configs are always allowed since they do not execute local code.
  • User-level configs (~/.deepagents/.mcp.json) are always trusted — the same trust model as config.toml and hooks.json.

​
Flags

FlagBehavior
--trust-project-mcpTrust all project-level stdio servers without prompting (for CI and automation)
# Skip the approval prompt
deepagents --trust-project-mcp

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

​
Trust store

Trust decisions are stored in ~/.deepagents/config.toml: 
[mcp_trust.projects]
"/Users/you/myproject" = "sha256:abc123..."
Each key is an absolute project root path. The value is a SHA-256 digest of the concatenated project-level config contents. To revoke trust, delete the entry or modify the project’s .mcp.json (which invalidates the fingerprint automatically).
A trusted stdio MCP server has the same permissions as your user account. Only approve servers from repositories you trust. Review the commands shown in the approval prompt before accepting.

​
Troubleshooting

Verify the command works outside the CLI:
npx -y @modelcontextprotocol/server-filesystem /tmp
Common causes: the package isn’t installed, npx isn’t on PATH, or required environment variables are missing.
Check that the remote server is running and the URL is correct. If the server requires authentication, make sure headers includes the correct credentials.
The CLI prints the number of tools loaded at startup (e.g., ✓ Loaded 3 MCP tools). If you see 0, the server started successfully but didn’t advertise any tools — check the server’s own logs or documentation.

​
Further reading

  • LangChain MCP guide — protocol details, building custom servers, and using langchain-mcp-adapters programmatically
  • MCP specification — the official protocol spec and server registry
Edit this page on GitHub or file an issue.
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.