MCP Tools ↗

Documentation Index#

Fetch the complete documentation index at: https://docs.langchain.com/llms.txt Use this file to discover all available pages before exploring further.

Load additional tools from MCP (Model Context Protocol) servers

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 .mcp.json file at your project root. The format follows the Claude Desktop convention:

    {
        "mcpServers": {
            "docs-langchain": {
            "type": "http",
            "url": "https://docs.langchain.com/mcp"
            }
        }
    }
    ```
  <span class="step-end"></span>

  <span class="step-marker" data-step-title="Launch the CLI"></span>
```bash
    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):

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#

--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.

{
  "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" }
    }
  }
}

Server types summary#

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:

{
  "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#

# 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.

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
    ```

Common causes: the package isn't installed, `npx` isn't on `PATH`, or required environment variables are missing.
  </Accordion>

  <Accordion title="Connection refused (SSE/HTTP)">
Check that the remote server is running and the URL is correct. If the server requires authentication, make sure `headers` includes the correct credentials.
  </Accordion>

  <Accordion title="Tools not appearing">
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.
  </Accordion>
</AccordionGroup>

## Further reading

* [LangChain MCP guide](/oss/python/langchain/mcp): protocol details, building custom servers, and using `langchain-mcp-adapters` programmatically
* [MCP specification](https://modelcontextprotocol.io/): the official protocol spec and server registry

***


  <span class="callout-start" data-callout-type="note"></span>
[Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/oss/deepagents/cli/mcp-tools.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
  <span class="callout-end"></span>

  <span class="callout-start" data-callout-type="note"></span>
[Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
  <span class="callout-end"></span>