mcp-management

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

MCP Server Management

MCP服务器管理

Expert knowledge for managing Model Context Protocol (MCP) servers on a project-by-project basis, with support for runtime management, OAuth remote servers, and dynamic server discovery.

针对逐个项目管理Model Context Protocol（MCP）服务器的专业知识，支持运行时管理、OAuth远程服务器和动态服务器发现。

When to Use This Skill

何时使用此技能

Use this skill when...	Use configure-mcp instead when...
Understanding MCP architecture and concepts	Setting up `.mcp.json` for a new project
Managing servers at runtime (enable/disable)	Installing new servers interactively
Setting up OAuth remote MCP servers	Running compliance checks on MCP configuration
Troubleshooting connection failures	Adding specific servers from the registry
Implementing `list_changed` dynamic discovery	Generating project standards reports

在此场景下使用本技能...	在此场景下改用configure-mcp...
理解MCP架构和概念	为新项目配置 `.mcp.json`
在运行时管理服务器（启用/禁用）	交互式安装新服务器
配置OAuth远程MCP服务器	对MCP配置执行合规性检查
排查连接失败问题	从注册表添加特定服务器
实现 `list_changed` 动态发现	生成项目标准报告

MCP Architecture Overview

MCP架构概述

MCP connects Claude Code to external tools and data sources via two transport types:

Transport	Usage	Auth	Configuration
Stdio (local)	Command-based servers via `npx` , `bunx` , `uvx` , `go run`	None needed	`.mcp.json`
HTTP+SSE (remote)	URL-based servers hosted externally	OAuth 2.1	`.mcp.json` with `url` field

MCP通过两种传输类型将Claude Code连接到外部工具和数据源：

传输类型	使用场景	认证方式	配置位置
Stdio（本地）	通过 `npx` 、 `bunx` 、 `uvx` 、 `go run` 运行的基于命令的服务器	无需认证	`.mcp.json`
HTTP+SSE（远程）	外部托管的基于URL的服务器	OAuth 2.1	带 `url` 字段的 `.mcp.json`

Local Server (Stdio)

本地服务器（Stdio）

json

{
  "mcpServers": {
    "context7": {
      "command": "bunx",
      "args": ["-y", "@upstash/context7-mcp"]
    }
  }
}

json

{
  "mcpServers": {
    "context7": {
      "command": "bunx",
      "args": ["-y", "@upstash/context7-mcp"]
    }
  }
}

Remote Server (HTTP+SSE with OAuth)

远程服务器（HTTP+SSE 带OAuth）

json

{
  "mcpServers": {
    "my-remote-server": {
      "url": "https://mcp.example.com/sse",
      "headers": {
        "Authorization": "Bearer ${MY_API_TOKEN}"
      }
    }
  }
}

json

{
  "mcpServers": {
    "my-remote-server": {
      "url": "https://mcp.example.com/sse",
      "headers": {
        "Authorization": "Bearer ${MY_API_TOKEN}"
      }
    }
  }
}

Runtime Server Management

运行时服务器管理

/mcp

Commands (Claude Code 2.1.50+)

/mcp

命令（Claude Code 2.1.50+）

Use these slash commands to manage servers without editing configuration files:

Command	Description
`/mcp`	List all configured MCP servers and their connection status
`/mcp enable <server>`	Enable a server for the current session
`/mcp disable <server>`	Disable a server for the current session (session-scoped only)

Note: Enable/disable are session-scoped. Edit

.mcp.json

for permanent changes.

使用这些斜杠命令无需编辑配置文件即可管理服务器：

命令	描述
`/mcp`	列出所有已配置的MCP服务器及其连接状态
`/mcp enable <server>`	在当前会话中启用服务器
`/mcp disable <server>`	在当前会话中禁用服务器（仅会话范围内有效）

注意：启用/禁用仅在会话范围内有效。如需永久更改，请编辑

.mcp.json

。

Check Server Status

检查服务器状态

bash

undefined

bash

undefined

List configured servers

列出已配置的服务器

jq -r '.mcpServers | keys[]' .mcp.json

Verify server config

验证服务器配置

jq '.mcpServers.context7' .mcp.json

undefined

jq '.mcpServers.context7' .mcp.json

undefined

OAuth Support for Remote MCP Servers

远程MCP服务器的OAuth支持

Claude Code 2.1.50+ includes improved OAuth handling for remote MCP servers:

Claude Code 2.1.50+ 包含针对远程MCP服务器的改进OAuth处理：

OAuth Flow Overview

OAuth流程概述

Remote MCP servers using HTTP+SSE transport use OAuth 2.1:

Claude Code discovers OAuth metadata from
```
/.well-known/oauth-authorization-server
```
Discovery metadata is cached to avoid repeated HTTP round-trips on session start
User authorizes in the browser; token is stored and reused across sessions
If additional permissions are needed mid-session, step-up auth is triggered

使用HTTP+SSE传输的远程MCP服务器采用OAuth 2.1：

Claude Code从
```
/.well-known/oauth-authorization-server
```
发现OAuth元数据
发现的元数据会被缓存，以避免会话启动时重复的HTTP往返
用户在浏览器中授权；令牌会被存储并在会话间复用
如果会话中需要额外权限，会触发升级认证

Step-Up Auth

升级认证

Step-up auth occurs when a tool requires elevated permissions not granted in the initial OAuth flow:

Server signals that additional scope is required
Claude Code prompts the user to re-authorize with the expanded scope
After re-authorization, the original tool call is retried automatically

当工具需要初始OAuth流程中未授予的更高权限时，会触发升级认证：

服务器发出信号表示需要额外权限范围
Claude Code提示用户使用扩展范围重新授权
重新授权后，原工具调用会自动重试

OAuth Discovery Caching

OAuth发现缓存

Metadata from

/.well-known/oauth-authorization-server

is cached per server URL. If a remote server changes its OAuth configuration, force a refresh by:

Using

/mcp disable <server>

then

/mcp enable <server>

in the session

Or restarting Claude Code to clear the cache

/.well-known/oauth-authorization-server

的元数据会按服务器URL进行缓存。如果远程服务器更改了OAuth配置，可通过以下方式强制刷新：

在会话中使用

/mcp disable <server>

然后

/mcp enable <server>

或重启Claude Code以清除缓存

Remote Server Configuration

远程服务器配置

json

{
  "mcpServers": {
    "my-service": {
      "url": "https://api.example.com/mcp/sse",
      "headers": {
        "Authorization": "Bearer ${MY_SERVICE_TOKEN}"
      }
    }
  }
}

Use

${VAR_NAME}

syntax for environment variable references — never hardcode tokens.

json

{
  "mcpServers": {
    "my-service": {
      "url": "https://api.example.com/mcp/sse",
      "headers": {
        "Authorization": "Bearer ${MY_SERVICE_TOKEN}"
      }
    }
  }
}

使用

${VAR_NAME}

语法引用环境变量——切勿硬编码令牌。

Dynamic Tool Discovery (

list_changed

)

动态工具发现（

list_changed

）

MCP servers that support the

list_changed

capability can update their tool list dynamically without requiring a session restart.

支持

list_changed

功能的MCP服务器可以动态更新其工具列表，无需重启会话。

How It Works

工作原理

Server declares
```
{"tools": {"listChanged": true}}
```
in its capabilities response
When the server's tool set changes, it sends
```
notifications/tools/list_changed
```
Claude Code refreshes its tool list from that server automatically
New tools become available immediately in the current session

服务器在其功能响应中声明
```
{"tools": {"listChanged": true}}
```
当服务器的工具集发生变化时，会发送
```
notifications/tools/list_changed
```
Claude Code会自动从该服务器刷新工具列表
新工具会立即在当前会话中可用

Practical Implications

实际意义

No session restart required when a server adds or removes tools dynamically
Useful for servers that expose project-context-specific tools

For

resources/list_changed

and

prompts/list_changed

— same pattern applies

无需重启会话即可动态添加或移除服务器工具
适用于暴露项目上下文特定工具的服务器

对于

resources/list_changed

和

prompts/list_changed

——采用相同模式

Checking Capabilities

检查功能

The capabilities are declared by the server during initialization. Claude Code subscribes automatically when the server declares support. No client-side configuration is required.

功能由服务器在初始化期间声明。当服务器声明支持时，Claude Code会自动订阅。无需客户端配置。

Troubleshooting

故障排查

Server Won't Connect

服务器无法连接

bash

undefined

bash

undefined

Verify server command is available

验证服务器命令是否可用

which bunx # or npx, uvx, go

which bunx # 或npx、uvx、go

Test server manually

手动测试服务器

bunx -y @upstash/context7-mcp # Should start without error

bunx -y @upstash/context7-mcp # 应无错误启动

Validate JSON syntax

验证JSON语法

jq empty .mcp.json && echo "JSON is valid" || echo "JSON syntax error"

undefined

jq empty .mcp.json && echo "JSON格式有效" || echo "JSON语法错误"

undefined

Missing Environment Variables

缺少环境变量

bash

undefined

bash

undefined

List all env vars referenced in .mcp.json

列出.mcp.json中引用的所有环境变量

jq -r '.mcpServers[] | .env // {} | to_entries[] | "(.key)=(.value)"' .mcp.json

Check which are set

检查哪些变量已设置

jq -r '.mcpServers[] | .env // {} | keys[]' .mcp.json | while read var; do clean_var=$(echo "$var" | sed 's/${//;s/}//') [ -z "${!clean_var}" ] && echo "MISSING: $clean_var" || echo "SET: $clean_var" done

undefined

jq -r '.mcpServers[] | .env // {} | keys[]' .mcp.json | while read var; do clean_var=$(echo "$var" | sed 's/${//;s/}//') [ -z "${!clean_var}" ] && echo "缺失: $clean_var" || echo "已设置: $clean_var" done

undefined

OAuth Remote Server Issues

OAuth远程服务器问题

Symptom	Likely Cause	Action
Authorization prompt repeats	Token not persisted	Check token storage permissions
Step-up auth loop	Scope mismatch	Revoke and re-authorize
Discovery fails	Server down or URL wrong	Verify server URL and connectivity
Cache stale	Server changed OAuth config	Disable/enable server to refresh

症状	可能原因	操作
授权提示重复	令牌未持久化	检查令牌存储权限
升级认证循环	权限范围不匹配	撤销并重新授权
发现失败	服务器宕机或URL错误	验证服务器URL和连通性
缓存过期	服务器更改了OAuth配置	禁用/启用服务器以刷新缓存

SDK MCP Server Race Condition (2.1.49/2.1.50)

SDK MCP服务器竞争条件（2.1.49/2.1.50）

When using

claude-agent-sdk

0.1.39 with MCP servers, a known race condition in SDK-based MCP servers causes

CLIConnectionError: ProcessTransport is not ready for writing

. Workaround: use pre-computed context or static stdio servers instead of SDK MCP servers.

当使用

claude-agent-sdk

0.1.39搭配MCP服务器时，基于SDK的MCP服务器存在已知的竞争条件，会导致

CLIConnectionError: ProcessTransport is not ready for writing

。解决方法：使用预计算上下文或静态stdio服务器替代SDK MCP服务器。

Configuration Patterns

配置模式

Project-Scoped (Recommended)

项目范围（推荐）

Store in

.mcp.json

at project root. Add to

.gitignore

for personal configs or track for team configs.

json

{
  "mcpServers": {
    "context7": {
      "command": "bunx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    }
  }
}

存储在项目根目录的

.mcp.json

中。个人配置可添加到

.gitignore

，团队配置可提交到版本控制。

json

{
  "mcpServers": {
    "context7": {
      "command": "bunx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    }
  }
}

User-Scoped (Personal)

用户范围（个人）

For servers you want available everywhere, add to

~/.claude/settings.json

json

{
  "mcpServers": {
    "my-personal-tool": {
      "command": "npx",
      "args": ["-y", "my-personal-mcp"]
    }
  }
}

如需在所有项目中使用服务器，可添加到

~/.claude/settings.json

：

json

{
  "mcpServers": {
    "my-personal-tool": {
      "command": "npx",
      "args": ["-y", "my-personal-mcp"]
    }
  }
}

Plugin-Scoped

插件范围

Plugins can declare MCP servers in

plugin.json

json

{
  "mcpServers": {
    "plugin-api": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/api-server",
      "args": ["--port", "8080"]
    }
  }
}

Or via external file:

"mcpServers": "./.mcp.json"

插件可在

plugin.json

中声明MCP服务器：

json

{
  "mcpServers": {
    "plugin-api": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/api-server",
      "args": ["--port", "8080"]
    }
  }
}

或通过外部文件：

"mcpServers": "./.mcp.json"

Agentic Optimizations

智能优化

Context	Command
Quick status check	`jq -c '.mcpServers \| keys' .mcp.json 2>/dev/null`
Validate JSON	`jq empty .mcp.json 2>&1`
List env vars needed	`jq -r '.mcpServers[] \| .env // {} \| keys[]' .mcp.json 2>/dev/null \| sort -u`
Check specific server	`jq -e '.mcpServers.context7' .mcp.json >/dev/null 2>&1 && echo "installed"`
Find servers in plugin	`find . -name '.mcp.json' -maxdepth 2`

场景	命令
快速状态检查	`jq -c '.mcpServers \| keys' .mcp.json 2>/dev/null`
验证JSON格式	`jq empty .mcp.json 2>&1`
列出所需环境变量	`jq -r '.mcpServers[] \| .env // {} \| keys[]' .mcp.json 2>/dev/null \| sort -u`
检查特定服务器	`jq -e '.mcpServers.context7' .mcp.json >/dev/null 2>&1 && echo "已安装"`
查找插件中的服务器	`find . -name '.mcp.json' -maxdepth 2`

Quick Reference

快速参考

Server Types by Transport

按传输类型分类的服务器类型

Type	When to Use	Example
`command` (stdio)	Local tools, no auth needed	`bunx` , `npx` , `uvx` , `go run`
`url` (HTTP+SSE)	Remote hosted servers, OAuth needed	`https://...`

类型	使用场景	示例
`command` （stdio）	本地工具，无需认证	`bunx` , `npx` , `uvx` , `go run`
`url` （HTTP+SSE）	远程托管服务器，需要OAuth	`https://...`

Key Files

关键文件

File	Purpose
`.mcp.json`	Project-level MCP server config (team-shareable)
`~/.claude/settings.json`	User-level MCP server config (personal)
`plugin.json`	Plugin-level MCP server declarations

文件	用途
`.mcp.json`	项目级MCP服务器配置（可团队共享）
`~/.claude/settings.json`	用户级MCP服务器配置（个人使用）
`plugin.json`	插件级MCP服务器声明

mcp-management

Original

Translation

MCP Server Management

MCP服务器管理

When to Use This Skill

何时使用此技能

MCP Architecture Overview

MCP架构概述

Local Server (Stdio)

本地服务器（Stdio）

Remote Server (HTTP+SSE with OAuth)

远程服务器（HTTP+SSE 带OAuth）

Runtime Server Management

运行时服务器管理

/mcp Commands (Claude Code 2.1.50+)

/mcp 命令（Claude Code 2.1.50+）

Check Server Status

检查服务器状态

List configured servers

列出已配置的服务器

Verify server config

验证服务器配置

OAuth Support for Remote MCP Servers

远程MCP服务器的OAuth支持

OAuth Flow Overview

OAuth流程概述

Step-Up Auth

升级认证

OAuth Discovery Caching

OAuth发现缓存

Remote Server Configuration

远程服务器配置

Dynamic Tool Discovery (list_changed)

动态工具发现（list_changed）

How It Works

工作原理

Practical Implications

实际意义

Checking Capabilities

检查功能

Troubleshooting

故障排查

Server Won't Connect

服务器无法连接

Verify server command is available

验证服务器命令是否可用

Test server manually

手动测试服务器

Validate JSON syntax

验证JSON语法

Missing Environment Variables

缺少环境变量

List all env vars referenced in .mcp.json

列出.mcp.json中引用的所有环境变量

Check which are set

检查哪些变量已设置

OAuth Remote Server Issues

OAuth远程服务器问题

SDK MCP Server Race Condition (2.1.49/2.1.50)

SDK MCP服务器竞争条件（2.1.49/2.1.50）

Configuration Patterns

配置模式

Project-Scoped (Recommended)

项目范围（推荐）

User-Scoped (Personal)

用户范围（个人）

Plugin-Scoped

插件范围

Agentic Optimizations

智能优化

Quick Reference

快速参考

Server Types by Transport

按传输类型分类的服务器类型

Key Files

关键文件

`/mcp`
Commands (Claude Code 2.1.50+)

`/mcp`
命令（Claude Code 2.1.50+）

Dynamic Tool Discovery (
`list_changed`
)

动态工具发现（
`list_changed`
）