| 1 | # MCP (External Tool Servers) |
| 2 | |
| 3 | DeepSeek TUI can load additional tools via MCP (Model Context Protocol). MCP servers are local processes that the TUI starts and communicates with over stdio. |
| 4 | |
| 5 | Browsing note: |
| 6 | - `web.run` is the canonical built-in browsing tool. |
| 7 | - `web_search` remains available as a compatibility alias for older prompts and integrations. |
| 8 | |
| 9 | Server mode note: |
| 10 | - `deepseek-tui serve --mcp` runs the MCP stdio server. |
| 11 | - `deepseek-tui serve --http` runs the runtime HTTP/SSE API (separate mode). |
| 12 | - The `deepseek` dispatcher exposes `deepseek mcp-server` as an equivalent stdio |
| 13 | entrypoint used by the split CLI. |
| 14 | |
| 15 | ## Bootstrap MCP Config |
| 16 | |
| 17 | Create a starter MCP config at your resolved MCP path: |
| 18 | |
| 19 | ```bash |
| 20 | deepseek-tui mcp init |
| 21 | ``` |
| 22 | |
| 23 | `deepseek-tui setup --mcp` performs the same MCP bootstrap alongside skills setup. |
| 24 | |
| 25 | Common management commands: |
| 26 | |
| 27 | ```bash |
| 28 | deepseek-tui mcp list |
| 29 | deepseek-tui mcp tools [server] |
| 30 | deepseek-tui mcp add <name> --command "<cmd>" --arg "<arg>" |
| 31 | deepseek-tui mcp add <name> --url "http://localhost:3000/mcp" |
| 32 | deepseek-tui mcp enable <name> |
| 33 | deepseek-tui mcp disable <name> |
| 34 | deepseek-tui mcp remove <name> |
| 35 | deepseek-tui mcp validate |
| 36 | ``` |
| 37 | |
| 38 | ## In-TUI Manager |
| 39 | |
| 40 | Inside the interactive TUI, `/mcp` opens a compact manager for the resolved |
| 41 | MCP config path. It shows each configured server, whether it is enabled or |
| 42 | disabled, its transport, command or URL, timeout values, connection errors, |
| 43 | and discovered tools/resources/prompts when discovery has been run. |
| 44 | |
| 45 | Supported in-TUI actions: |
| 46 | |
| 47 | ```text |
| 48 | /mcp init |
| 49 | /mcp init --force |
| 50 | /mcp add stdio <name> <command> [args...] |
| 51 | /mcp add http <name> <url> |
| 52 | /mcp enable <name> |
| 53 | /mcp disable <name> |
| 54 | /mcp remove <name> |
| 55 | /mcp validate |
| 56 | /mcp reload |
| 57 | ``` |
| 58 | |
| 59 | `/mcp validate` and `/mcp reload` reconnect for UI discovery and refresh the |
| 60 | manager snapshot. Config edits made from the TUI are written immediately, but |
| 61 | the model-visible MCP tool pool is not hot-reloaded; the manager marks this as |
| 62 | restart-required until the TUI is restarted. |
| 63 | |
| 64 | ## Config File Location |
| 65 | |
| 66 | Default path: |
| 67 | |
| 68 | - `~/.deepseek/mcp.json` |
| 69 | |
| 70 | Overrides: |
| 71 | |
| 72 | - Config: `mcp_config_path = "/path/to/mcp.json"` |
| 73 | - Env: `DEEPSEEK_MCP_CONFIG=/path/to/mcp.json` |
| 74 | |
| 75 | `deepseek-tui mcp init` (and `deepseek-tui setup --mcp`) writes to this resolved path. |
| 76 | |
| 77 | The interactive `/config` editor also exposes `mcp_config_path`. Changing it in |
| 78 | the TUI updates the path used by `/mcp`, and requires a restart before the |
| 79 | model-visible MCP tool pool is rebuilt. |
| 80 | |
| 81 | After editing the file or changing `mcp_config_path`, restart the TUI. |
| 82 | |
| 83 | ## Tool Naming |
| 84 | |
| 85 | Discovered MCP tools are exposed to the model as: |
| 86 | |
| 87 | - `mcp_<server>_<tool>` |
| 88 | |
| 89 | Example: a server named `git` with a tool named `status` becomes `mcp_git_status`. |
| 90 | |
| 91 | The command palette includes MCP entries grouped by server. It shows disabled |
| 92 | and failed servers instead of hiding them, and uses the same runtime tool names |
| 93 | shown to the model. |
| 94 | |
| 95 | ## Resource and Prompt Helpers |
| 96 | |
| 97 | The CLI also exposes helper tools when MCP is enabled: |
| 98 | |
| 99 | - `list_mcp_resources` (optional `server` filter) |
| 100 | - `list_mcp_resource_templates` (optional `server` filter) |
| 101 | - `mcp_read_resource` / `read_mcp_resource` (aliases) |
| 102 | - `mcp_get_prompt` |
| 103 | |
| 104 | ## Minimal Example |
| 105 | |
| 106 | ```json |
| 107 | { |
| 108 | "timeouts": { |
| 109 | "connect_timeout": 10, |
| 110 | "execute_timeout": 60, |
| 111 | "read_timeout": 120 |
| 112 | }, |
| 113 | "servers": { |
| 114 | "example": { |
| 115 | "command": "node", |
| 116 | "args": ["./path/to/your-mcp-server.js"], |
| 117 | "env": {}, |
| 118 | "disabled": false |
| 119 | } |
| 120 | } |
| 121 | } |
| 122 | ``` |
| 123 | |
| 124 | You can also use `mcpServers` instead of `servers` for compatibility with other clients. |
| 125 | |
| 126 | ## Running DeepSeek as an MCP Server |
| 127 | |
| 128 | You can register your local DeepSeek binary as an MCP server so other DeepSeek sessions (or any MCP client) can call its tools. |
| 129 | |
| 130 | ### Quick Setup |
| 131 | |
| 132 | ```bash |
| 133 | deepseek-tui mcp add-self |
| 134 | ``` |
| 135 | |
| 136 | This resolves the current binary path, generates a config entry that runs `deepseek-tui serve --mcp`, and writes it to your MCP config file. The default server name is `deepseek`. |
| 137 | |
| 138 | Options: |
| 139 | |
| 140 | - `--name <NAME>` — custom server name (default: `deepseek`) |
| 141 | - `--workspace <PATH>` — workspace directory for the server |
| 142 | |
| 143 | ### Manual Config |
| 144 | |
| 145 | Equivalent manual entry in `~/.deepseek/mcp.json`: |
| 146 | |
| 147 | ```json |
| 148 | { |
| 149 | "servers": { |
| 150 | "deepseek": { |
| 151 | "command": "/path/to/deepseek", |
| 152 | "args": ["serve", "--mcp"], |
| 153 | "env": {} |
| 154 | } |
| 155 | } |
| 156 | } |
| 157 | ``` |
| 158 | |
| 159 | The `deepseek-tui` binary supports `serve --mcp` directly. The `deepseek` |
| 160 | dispatcher offers the equivalent `deepseek mcp-server` stdio entrypoint. Use |
| 161 | whichever is on your `PATH` (run `which deepseek` or `which deepseek-tui` to |
| 162 | find the full path). The `mcp add-self` command automatically resolves the |
| 163 | correct binary. |
| 164 | |
| 165 | ### Prerequisites |
| 166 | |
| 167 | - The binary referenced in `command` must exist and be executable. |
| 168 | - The MCP server runs as a child process via stdio — no network ports required. |
| 169 | - Each MCP client session spawns its own server process. |
| 170 | |
| 171 | ### Tool Naming |
| 172 | |
| 173 | Tools from a self-hosted DeepSeek server follow the standard naming convention: |
| 174 | |
| 175 | - `mcp_deepseek_<tool>` (if the server is named `deepseek`) |
| 176 | |
| 177 | For example, the `shell` tool becomes `mcp_deepseek_shell`. |
| 178 | |
| 179 | ### MCP Server vs HTTP/SSE API vs ACP |
| 180 | |
| 181 | | | `deepseek-tui serve --mcp` | `deepseek-tui serve --http` | `deepseek-tui serve --acp` | |
| 182 | |---|---|---|---| |
| 183 | | **Protocol** | MCP stdio | HTTP/SSE JSON-RPC | ACP stdio | |
| 184 | | **Use case** | Tool server for MCP clients | Runtime API for apps | Editor agent for Zed/custom ACP clients | |
| 185 | | **Config** | `~/.deepseek/mcp.json` entry | Direct URL connection | Editor `agent_servers` custom command | |
| 186 | | **Lifecycle** | Spawned per client session | Long-running daemon | Spawned per editor agent session | |
| 187 | |
| 188 | Use `mcp add-self` when you want DeepSeek tools available to other MCP clients. |
| 189 | Use `serve --http` when building applications that consume the API directly. |
| 190 | Use `serve --acp` when an editor wants to talk to DeepSeek as an ACP agent. |
| 191 | |
| 192 | ### Verification |
| 193 | |
| 194 | After adding, test the connection: |
| 195 | |
| 196 | ```bash |
| 197 | deepseek-tui mcp validate |
| 198 | deepseek-tui mcp tools deepseek |
| 199 | ``` |
| 200 | |
| 201 | ## Server Fields |
| 202 | |
| 203 | Per-server settings: |
| 204 | |
| 205 | - `command` (string, required) |
| 206 | - `args` (array of strings, optional) |
| 207 | - `env` (object, optional) |
| 208 | - `connect_timeout`, `execute_timeout`, `read_timeout` (seconds, optional) |
| 209 | - `disabled` (bool, optional) |
| 210 | - `enabled` (bool, optional, default `true`) |
| 211 | - `required` (bool, optional): startup/connect validation fails if this server cannot initialize. |
| 212 | - `enabled_tools` (array, optional): allowlist of tool names for this server. |
| 213 | - `disabled_tools` (array, optional): denylist applied after `enabled_tools`. |
| 214 | |
| 215 | ## Safety Notes |
| 216 | |
| 217 | MCP tools now flow through the same tool-approval framework as built-in tools. Read-only MCP helpers (resource/prompt listing and reads) can run without prompts in suggestive approval modes, while side-effectful MCP tools require approval. |
| 218 | |
| 219 | You should still only configure MCP servers you trust, and treat MCP server configuration as equivalent to running code on your machine. |
| 220 | |
| 221 | ## Troubleshooting |
| 222 | |
| 223 | - Run `deepseek-tui doctor` to confirm the MCP config path it resolved and whether it exists. |
| 224 | - In the TUI, run `/mcp validate` to refresh the visible server/tool snapshot. |
| 225 | - If the MCP config is missing, run `deepseek-tui mcp init --force` to regenerate it. |
| 226 | - If tools don’t appear, verify the server command works from your shell and that the server supports MCP `tools/list`. |
| 227 |