/.mcp.json` | Project-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
| Flag | Behavior |
| ------------------- | -------------------------------------------------------------------------------------------------- |
| `--mcp-config PATH` | Add an explicit config as the highest-precedence source (merged on top of auto-discovered configs) |
| `--no-mcp` | Disable 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.
```json title="mcp-config.json" theme={null}
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
"env": {}
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": { "GITHUB_TOKEN": "your-token" }
}
}
}
```
The executable to run.
Arguments passed to the command.
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`:
```json title="mcp-config.json" theme={null}
{
"mcpServers": {
"remote-api": {
"type": "sse",
"url": "https://api.example.com/mcp",
"headers": { "Authorization": "Bearer your-token" }
}
}
}
```
Transport type: `"sse"` for Server-Sent Events or `"http"` for streamable HTTP.
The server endpoint URL.
HTTP headers sent with every request. Commonly used for authentication.
### Server types summary
| Type | Required fields | Optional fields |
| --------------- | --------------------- | --------------- |
| stdio (default) | `command` | `args`, `env` |
| sse | `type: "sse"`, `url` | `headers` |
| http | `type: "http"`, `url` | `headers` |
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:
```json title="mcp-config.json" theme={null}
{
"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
| Flag | Behavior |
| --------------------- | ------------------------------------------------------------------------------- |
| `--trust-project-mcp` | Trust all project-level stdio servers without prompting (for CI and automation) |
```bash theme={null}
# 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`:
```toml theme={null}
[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:
```bash theme={null}
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](/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
***
[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).
[Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.