From 8d8babe1265d6b221c8d61bc0ef76c64ef7219d0 Mon Sep 17 00:00:00 2001 From: Brian Sparker Date: Mon, 27 Jul 2026 16:29:59 -0400 Subject: [PATCH] docs: add an authenticated HTTP MCP server example The optional-fields table documents `bearerTokenEnvVar` and `enabledTools`, but the only worked examples on the page are an unauthenticated HTTP entry and two stdio entries, so neither field is shown in use. Add a short subsection to Configuration that connects one real HTTP server both with and without credentials, and narrows it with `enabledTools`. Co-Authored-By: Claude Opus 5 (1M context) --- docs/en/customization/mcp.md | 34 ++++++++++++++++++++++++++++++++++ docs/zh/customization/mcp.md | 34 ++++++++++++++++++++++++++++++++++ 2 files changed, 68 insertions(+) diff --git a/docs/en/customization/mcp.md b/docs/en/customization/mcp.md index 2768220074..a3e72d2d4a 100644 --- a/docs/en/customization/mcp.md +++ b/docs/en/customization/mcp.md @@ -67,6 +67,40 @@ Plugins can also declare MCP servers in their manifest. Servers declared by a pl stdio entries in a project-level `.kimi-code/mcp.json` execute local commands when a session starts. Only enable these in repositories you trust. ::: +### Example: an authenticated HTTP server + +The optional fields above are easier to place against a concrete server. [You.com](https://you.com/docs/build-with-agents/mcp-server?utm_source=moonshotai-kimi-code&utm_medium=oss_integration&utm_campaign=2026-07-oss-integrations&utm_content=docs) serves web search over HTTP and can be connected with or without credentials: + +```json +{ + "mcpServers": { + "you-free": { + "url": "https://api.you.com/mcp?profile=free" + }, + "you": { + "url": "https://api.you.com/mcp", + "bearerTokenEnvVar": "YDC_API_KEY" + } + } +} +``` + +`you-free` needs no credentials and exposes `you-search` on its own. The authenticated entry reads its token from `$YDC_API_KEY` and additionally exposes `you-contents`, `you-research`, `you-discover`, and `you-balance`. To authorize through the browser instead of a static token, omit `bearerTokenEnvVar` and run `/mcp-config login you`. + +Use `enabledTools` to narrow a server down to the tools you actually want: + +```json +{ + "mcpServers": { + "you": { + "url": "https://api.you.com/mcp", + "bearerTokenEnvVar": "YDC_API_KEY", + "enabledTools": ["you-search", "you-contents"] + } + } +} +``` + ## Tool Naming and Permissions MCP tools are named in the format `mcp____`, for example `mcp__github__create_issue`. Permission rules support `*` and `**` wildcards, for example `mcp__github__*` matches all tools under that server. MCP tool parameters are not included in permission matching. diff --git a/docs/zh/customization/mcp.md b/docs/zh/customization/mcp.md index 93cb8031c9..c52ef53a47 100644 --- a/docs/zh/customization/mcp.md +++ b/docs/zh/customization/mcp.md @@ -67,6 +67,40 @@ Plugins 也可以在 manifest 中声明 MCP servers。Plugin 声明的 servers 项目级 `.kimi-code/mcp.json` 中的 stdio 条目会在会话启动时执行本地命令，只在你信任的仓库里启用。 ::: +### 示例：带鉴权的 HTTP server + +结合一个真实的 server 更容易理解上面这些可选字段。[You.com](https://you.com/docs/build-with-agents/mcp-server?utm_source=moonshotai-kimi-code&utm_medium=oss_integration&utm_campaign=2026-07-oss-integrations&utm_content=docs) 通过 HTTP 提供网页搜索，可以在有凭证和无凭证两种方式下连接： + +```json +{ + "mcpServers": { + "you-free": { + "url": "https://api.you.com/mcp?profile=free" + }, + "you": { + "url": "https://api.you.com/mcp", + "bearerTokenEnvVar": "YDC_API_KEY" + } + } +} +``` + +`you-free` 不需要凭证，只提供 `you-search`。带鉴权的条目从 `$YDC_API_KEY` 读取 token，并额外提供 `you-contents`、`you-research`、`you-discover` 和 `you-balance`。如果想用浏览器授权而不是静态 token，去掉 `bearerTokenEnvVar` 并运行 `/mcp-config login you`。 + +用 `enabledTools` 可以把 server 收窄到你真正需要的工具： + +```json +{ + "mcpServers": { + "you": { + "url": "https://api.you.com/mcp", + "bearerTokenEnvVar": "YDC_API_KEY", + "enabledTools": ["you-search", "you-contents"] + } + } +} +``` + ## 工具命名与权限 MCP 工具按 `mcp____` 格式命名，例如 `mcp__github__create_issue`。权限规则中支持 `*` 和 `**` 通配，例如 `mcp__github__*` 命中该 server 下所有工具。MCP 工具参数不参与权限匹配。