Skip to content

feat(mcp): support remote MCP servers over Streamable HTTP #198

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
gtxy27 wants to merge 4 commits into
base: main
Choose a base branch
from
Open

feat(mcp): support remote MCP servers over Streamable HTTP #198

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ed145e0
refactor(mcp): extract transport abstraction from McpClient
gtxy27 Jun 25, 2026
5315fed
feat(mcp): support remote servers over Streamable HTTP
gtxy27 Jun 25, 2026
42efcf9
feat(settings): resolve remote MCP servers from mcpServers
gtxy27 Jun 25, 2026
57fabc4
docs(mcp): document remote Streamable HTTP servers
gtxy27 Jun 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README-en.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -133,7 +133,7 @@ Yes. Just set `env.BASE_URL` in `~/.deepcode/settings.json` to an OpenAI-compati

### How do I configure MCP?

Deep Code supports MCP (Model Context Protocol) to connect external services such as GitHub, browsers, databases, and more. Configure the `mcpServers` field in `settings.json` to enable it, then use the `/mcp` command to view MCP server status and available tools.
Deep Code supports MCP (Model Context Protocol) to connect external services such as GitHub, browsers, databases, and more. Configure the `mcpServers` field in `settings.json` to enable it — both local stdio servers and remote Streamable HTTP servers are supported — then use the `/mcp` command to view MCP server status and available tools.

For detailed setup instructions, see: [docs/mcp.md](docs/mcp.md)

Expand Down
2 changes: 1 addition & 1 deletion README-zh_CN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -118,7 +118,7 @@ Deep Code自带免费的、且大部分情况够用的Web Search工具。如果

### 如何配置 MCP？

Deep Code 支持 MCP（Model Context Protocol），可以连接 GitHub、浏览器、数据库等外部服务。在 `settings.json` 中配置 `mcpServers` 字段即可启用，启动后使用 `/mcp` 命令查看已配置的 MCP 服务器状态和可用工具。
Deep Code 支持 MCP（Model Context Protocol），可以连接 GitHub、浏览器、数据库等外部服务。在 `settings.json` 中配置 `mcpServers` 字段即可启用，既支持本地 stdio 服务器，也支持远程 Streamable HTTP 服务器；启动后使用 `/mcp` 命令查看已配置的 MCP 服务器状态和可用工具。

详细配置指南：[docs/mcp.md](docs/mcp.md)

Expand Down
2 changes: 1 addition & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -118,7 +118,7 @@ Deep Code自带免费的、且大部分情况够用的Web Search工具。如果

### 如何配置 MCP？

Deep Code 支持 MCP（Model Context Protocol），可以连接 GitHub、浏览器、数据库等外部服务。在 `settings.json` 中配置 `mcpServers` 字段即可启用，启动后使用 `/mcp` 命令查看已配置的 MCP 服务器状态和可用工具。
Deep Code 支持 MCP（Model Context Protocol），可以连接 GitHub、浏览器、数据库等外部服务。在 `settings.json` 中配置 `mcpServers` 字段即可启用，既支持本地 stdio 服务器，也支持远程 Streamable HTTP 服务器；启动后使用 `/mcp` 命令查看已配置的 MCP 服务器状态和可用工具。

详细配置指南：[docs/mcp.md](docs/mcp.md)

Expand Down
31 changes: 30 additions & 1 deletion docs/mcp.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,9 +43,38 @@ MCP 工具在 Deep Code 中的命名格式为 `mcp__<服务名>__<工具名>`，

| 字段 | 类型 | 必填 | 说明 |
| --------- | -------- | ---- | ---------------------------------------------------------------------------------------------------------------------- |
| `command` | string | 是 | MCP 服务器的可执行文件路径或命令（如 `npx`、`node`、`python`）。当命令是 `npx` 时，Deep Code 会自动在参数前补充 `-y`。 |
| `command` | string | 否 | 本地 stdio 服务器的可执行文件路径或命令（如 `npx`、`node`、`python`）。当命令是 `npx` 时，Deep Code 会自动在参数前补充 `-y`。 |
| `args` | string[] | 否 | 传递给命令的参数列表 |
| `env` | object | 否 | 传递给 MCP 服务器进程的环境变量（如 API Key） |
| `type` | string | 否 | 传输类型：`stdio`（本地子进程，默认）或 `http`（远程 Streamable HTTP）。给出 `url` 时默认为 `http`。 |
| `url` | string | 否 | 远程 MCP 服务器的 HTTP(S) 端点（Streamable HTTP）。设置后即为远程服务器，无需 `command`。 |
| `headers` | object | 否 | 远程请求附带的 HTTP 头（如 `Authorization`），常用于鉴权。 |

> 本地服务器用 `command`/`args`/`env`，远程服务器用 `url`/`headers`，二者择一。

## 远程 MCP 服务器（Streamable HTTP）

除了本地 stdio 服务器，Deep Code 也支持通过 **Streamable HTTP**（MCP 2025-03-26）连接远程 MCP 服务器。只要在配置里给出 `url`（或显式设置 `type: "http"`）即可：

```json
{
"mcpServers": {
"remote-service": {
"type": "http",
"url": "https://example.com/mcp",
"headers": {
"Authorization": "Bearer <token>"
}
}
}
}
```

- `url`：远程服务器的 HTTP(S) 端点。
- `headers`：可选，附加到每个请求的 HTTP 头，常用于鉴权（如 `Authorization`）。
- 初始化时服务器返回的 `Mcp-Session-Id` 会被自动记录，并在后续请求中回传。

> 当前仅支持 Streamable HTTP；尚不支持旧版 HTTP+SSE 双端点传输与 OAuth 授权流程。

## 常用 MCP 示例

Expand Down
31 changes: 30 additions & 1 deletion docs/mcp_en.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,9 +43,38 @@ Edit `~/.deepcode/settings.json` and add the `mcpServers` field:

| Field | Type | Required | Description |
| --------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `command` | string | Yes | Path or command of the MCP server executable (e.g., `npx`, `node`, `python`). When the command is `npx`, Deep Code automatically prepends `-y` to the arguments. |
| `command` | string | No | Executable path or command for a local stdio server (e.g., `npx`, `node`, `python`). When the command is `npx`, Deep Code automatically prepends `-y` to the arguments. |
| `args` | string[] | No | List of arguments to pass to the command |
| `env` | object | No | Environment variables (e.g., API keys) to pass to the MCP server process |
| `type` | string | No | Transport: `stdio` (local subprocess, default) or `http` (remote Streamable HTTP). Defaults to `http` when a `url` is given. |
| `url` | string | No | HTTP(S) endpoint of a remote MCP server (Streamable HTTP). When set, the server is remote and no `command` is needed. |
| `headers` | object | No | HTTP headers (e.g., `Authorization`) sent with each remote request, typically for authentication. |

> Use `command`/`args`/`env` for local servers, or `url`/`headers` for remote servers — one or the other.

## Remote MCP Servers (Streamable HTTP)

In addition to local stdio servers, Deep Code can connect to remote MCP servers over **Streamable HTTP** (MCP 2025-03-26). Just provide a `url` (or set `type: "http"` explicitly):

```json
{
"mcpServers": {
"remote-service": {
"type": "http",
"url": "https://example.com/mcp",
"headers": {
"Authorization": "Bearer <token>"
}
}
}
}
```

- `url`: the remote server's HTTP(S) endpoint.
- `headers`: optional HTTP headers attached to every request, typically for authentication (e.g., `Authorization`).
- The `Mcp-Session-Id` returned by the server on initialize is captured automatically and echoed on subsequent requests.

> Only Streamable HTTP is supported for now; the legacy two-endpoint HTTP+SSE transport and OAuth authorization flows are not yet handled.

## Common MCP Examples

Expand Down
Loading