Tools and plugins

模型上下文协议 (MCP)

模型上下文协议 (MCP) 这一页讲的，就是模型上下文协议 (MCP) 这件事在 Claude Code 里到底怎么用。

页面信息

对应原页

模型上下文协议 (MCP)

页面性质

第三方中文解释页

使用建议

先看人话解释，再对照原页命令和代码

这页不是官方原文，而是顺着官方文档结构做的中文解释版。命令、参数、配置名这些硬东西尽量保留，解释部分则尽量讲成人能照着做的话。

如果你碰到特别敏感的配置、权限或企业环境差异，最好顺手点上面的“查看原始文档”再核一遍。

这一页先讲明白

MCP 是 Claude Code 接外部工具和数据源的标准接口。

有了它，Claude 不只看本地代码，还能摸到数据库、文档、工单、聊天记录这些外部材料。

这东西像给帮工接上外接设备。原来它只在你院里转，现在能去仓库看账本、去办公室翻工单。

重点不是“连得多”，而是“连得准”。先接最能帮你做决策的外部信息。

先决定你最缺哪种外部信息，再去接对应的 MCP 服务。

接好后先试只读类场景，确认数据能看懂，再慢慢放到写入类操作。

最常见的接法

先从读取外部信息开始，风险最小。

1. 连接设计文档
2. 读取工单系统
3. 查看团队聊天记录
4. 调用自定义内部工具

预留广告位

正文中段响应式广告 等你后面真接 AdSense，这里再放正式广告。

Documentation Index

这里不是让你背"Documentation Index"这个词，而是让你看它真干活时怎么使。

看这段时要特别盯工具和权限边界，别为了省事一把全开。

What you can do with MCP

这里不是让你背"What you can do with MCP"这个词，而是让你看它真干活时怎么使。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

Popular MCP servers

这一块主要是在说"Popular MCP servers"真到手上该怎么用，哪里最容易踩坑。

如果你打算把外接能力往里挂，这里提到的 hooks、MCP、skills、memory 都要分清各自负责哪一摊。

Installing MCP servers

看到这里，就把"Installing MCP servers"当成一件真要上手的活来看。

如果你打算把外接能力往里挂，这里提到的 hooks、MCP、skills、memory 都要分清各自负责哪一摊。

Option 1: Add a remote HTTP server

这一块主要是在说"Option 1: Add a remote HTTP server"真到手上该怎么用，哪里最容易踩坑。

如果你打算把外接能力往里挂，这里提到的 hooks、MCP、skills、memory 都要分清各自负责哪一摊。

终端里敲

Option 1: Add a remote HTTP server

看到这里，别光点头，下面这条命令先跑起来再说。

# Basic syntax
claude mcp add --transport http <name> <url>

# Real example: Connect to Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Example with Bearer token
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

Option 2: Add a remote SSE server

这一段不只是挂个标题，它是在说明"Option 2: Add a remote SSE server"这一块到底负责什么。

终端里敲

Option 2: Add a remote SSE server

看到这里，别光点头，下面这条命令先跑起来再说。

# Basic syntax
claude mcp add --transport sse <name> <url>

# Real example: Connect to Asana
claude mcp add --transport sse asana https://mcp.asana.com/sse

# Example with authentication header
claude mcp add --transport sse private-api https://api.company.com/sse \
  --header "X-API-Key: your-key-here"

Option 3: Add a local stdio server

这一块主要是在说"Option 3: Add a local stdio server"真到手上该怎么用，哪里最容易踩坑。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

终端里敲

Option 3: Add a local stdio server

看到这里，别光点头，下面这条命令先跑起来再说。

# Basic syntax
claude mcp add [options] <name> -- <command> [args...]

# Real example: Add Airtable server
claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \
  -- npx -y airtable-mcp-server

Managing your servers

看到这里，就把"Managing your servers"当成一件真要上手的活来看。

看这段时要特别盯工具和权限边界，别为了省事一把全开。

终端里敲

Managing your servers

这一段不是只让你理解意思，下面这条命令就是现在要跑的。

# List all configured servers
claude mcp list

# Get details for a specific server
claude mcp get github

# Remove a server
claude mcp remove github

# (within Claude Code) Check server status
/mcp

Dynamic tool updates

这一块主要是在说"Dynamic tool updates"真到手上该怎么用，哪里最容易踩坑。

看这段时要特别盯工具和权限边界，别为了省事一把全开。

Automatic reconnection

这一段更像在讲判断条件，什么时候该上，什么时候先别急。把触发条件看清，比背标题更重要。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

Push messages with channels

这一段主要是在把"Push messages with channels"讲实，不是只摆个标题给你看。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

Plugin-provided MCP servers

看到这里，就把"Plugin-provided MCP servers"当成一件真要上手的活来看。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

改配置

Plugin-provided MCP servers 1

这一段说完，最后还得写到配置里才算真的生效。

{
  "mcpServers": {
    "database-tools": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_URL": "${DB_URL}"
      }
    }
  }
}

改配置

Plugin-provided MCP servers 2

这一段说完，最后还得写到配置里才算真的生效。

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

直接对 Claude 说

Plugin-provided MCP servers 3

这一步不用你自己动手配什么，把下面这句话交出去就行。

# Within Claude Code, see all MCP servers including plugin ones
/mcp

MCP installation scopes

看到这里，就把"MCP installation scopes"当成一件真要上手的活来看。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

Local scope

这一块主要是在说"Local scope"真到手上该怎么用，哪里最容易踩坑。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

终端里敲

Local scope 1

看到这里，别光点头，下面这条命令先跑起来再说。

# Add a local-scoped server (default)
claude mcp add --transport http stripe https://mcp.stripe.com

# Explicitly specify local scope
claude mcp add --transport http stripe --scope local https://mcp.stripe.com

改配置

Local scope 2

想把这条规矩固定住，就把下面这块老老实实写进去。

{
  "projects": {
    "/path/to/your/project": {
      "mcpServers": {
        "stripe": {
          "type": "http",
          "url": "https://mcp.stripe.com"
        }
      }
    }
  }
}

Project scope

这一块主要是在说"Project scope"真到手上该怎么用，哪里最容易踩坑。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

终端里敲

Project scope 1

看到这里，别光点头，下面这条命令先跑起来再说。

# Add a project-scoped server
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

改配置

Project scope 2

想把这条规矩固定住，就把下面这块老老实实写进去。

{
  "mcpServers": {
    "shared-server": {
      "command": "/path/to/server",
      "args": [],
      "env": {}
    }
  }
}

User scope

这一块主要是在说"User scope"真到手上该怎么用，哪里最容易踩坑。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

终端里敲

User scope

看到这里，别光点头，下面这条命令先跑起来再说。

# Add a user server
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

Scope hierarchy and precedence

这一段更像在讲判断条件，什么时候该上，什么时候先别急。把触发条件看清，比背标题更重要。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

Environment variable expansion in .mcp.json

这一块主要是在说"Environment variable expansion in .mcp.json"真到手上该怎么用，哪里最容易踩坑。

看这段时要特别盯工具和权限边界，别为了省事一把全开。

改配置

Environment variable expansion in .mcp.json

想把这条规矩固定住，就把下面这块老老实实写进去。

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

Practical examples

这里不是让你背"Practical examples"这个词，而是让你看它真干活时怎么使。

Example: Monitor errors with Sentry

这一段主要是在把"Example: Monitor errors with Sentry"讲实，不是只摆个标题给你看。

终端里敲

Example: Monitor errors with Sentry 1

先别急着往下翻，下面这条命令跑完，心里才有底。

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

直接对 Claude 说

Example: Monitor errors with Sentry 2

最省事的做法，就是把下面这句原样说给 Claude。

/mcp

直接对 Claude 说

Example: Monitor errors with Sentry 3

最省事的做法，就是把下面这句原样说给 Claude。

What are the most common errors in the last 24 hours?

直接对 Claude 说

Example: Monitor errors with Sentry 4

最省事的做法，就是把下面这句原样说给 Claude。

Show me the stack trace for error ID abc123

直接对 Claude 说

Example: Monitor errors with Sentry 5

最省事的做法，就是把下面这句原样说给 Claude。

Which deployment introduced these new errors?

Example: Connect to GitHub for code reviews

这一块主要是在说"Example: Connect to GitHub for code reviews"真到手上该怎么用，哪里最容易踩坑。

如果你打算把外接能力往里挂，这里提到的 hooks、MCP、skills、memory 都要分清各自负责哪一摊。

终端里敲

Example: Connect to GitHub for code reviews 1

看到这里，别光点头，下面这条命令先跑起来再说。

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

关键片段

Example: Connect to GitHub for code reviews 2

"Example: Connect to GitHub for code reviews"这一段里最要紧的原始写法在下面，先看它怎么落地。

Review PR #456 and suggest improvements

直接对 Claude 说

Example: Connect to GitHub for code reviews 3

到这里其实就剩一句话，把下面这句发出去就行。

Create a new issue for the bug we just found

直接对 Claude 说

Example: Connect to GitHub for code reviews 4

到这里其实就剩一句话，把下面这句发出去就行。

Show me all open PRs assigned to me

Example: Query your PostgreSQL database

这一段主要是在把"Example: Query your PostgreSQL database"讲实，不是只摆个标题给你看。

终端里敲

Example: Query your PostgreSQL database 1

先别急着往下翻，下面这条命令跑完，心里才有底。

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

直接对 Claude 说

Example: Query your PostgreSQL database 2

最省事的做法，就是把下面这句原样说给 Claude。

What's our total revenue this month?

直接对 Claude 说

Example: Query your PostgreSQL database 3

最省事的做法，就是把下面这句原样说给 Claude。

Show me the schema for the orders table

直接对 Claude 说

Example: Query your PostgreSQL database 4

最省事的做法，就是把下面这句原样说给 Claude。

Find customers who haven't made a purchase in 90 days

Authenticate with remote MCP servers

这一段就是验收，看它到底有没有真的通。

如果你打算把外接能力往里挂，这里提到的 hooks、MCP、skills、memory 都要分清各自负责哪一摊。

终端里敲

Authenticate with remote MCP servers 1

看到这里，别光点头，下面这条命令先跑起来再说。

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

直接对 Claude 说

Authenticate with remote MCP servers 2

到这里其实就剩一句话，把下面这句发出去就行。

/mcp

Use a fixed OAuth callback port

这一块主要是在说"Use a fixed OAuth callback port"真到手上该怎么用，哪里最容易踩坑。

如果你打算把外接能力往里挂，这里提到的 hooks、MCP、skills、memory 都要分清各自负责哪一摊。

终端里敲

Use a fixed OAuth callback port

看到这里，别光点头，下面这条命令先跑起来再说。

# Fixed callback port with dynamic client registration
claude mcp add --transport http \
  --callback-port 8080 \
  my-server https://mcp.example.com/mcp

Use pre-configured OAuth credentials

这里不是让你背"Use pre-configured OAuth credentials"这个词，而是让你看它真干活时怎么使。

如果你打算把外接能力往里挂，这里提到的 hooks、MCP、skills、memory 都要分清各自负责哪一摊。

终端里敲

Use pre-configured OAuth credentials 1

真到动手的时候了，下面这条直接敲一遍，看它回什么。

claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

终端里敲

Use pre-configured OAuth credentials 2

真到动手的时候了，下面这条直接敲一遍，看它回什么。

claude mcp add-json my-server \
  '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' \
  --client-secret

终端里敲

Use pre-configured OAuth credentials 3

真到动手的时候了，下面这条直接敲一遍，看它回什么。

claude mcp add-json my-server \
  '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"callbackPort":8080}}'

关键片段

Use pre-configured OAuth credentials 4

下面这块是这一段最值钱的原文样板，先对着看一眼。

MCP_CLIENT_SECRET=your-secret claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

Override OAuth metadata discovery

这里不是让你背"Override OAuth metadata discovery"这个词，而是让你看它真干活时怎么使。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

改配置

Override OAuth metadata discovery

光知道意思还不够，这里得把规矩落进配置里，下面这块照着填。

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "authServerMetadataUrl": "https://auth.example.com/.well-known/openid-configuration"
      }
    }
  }
}

Restrict OAuth scopes

这里不是让你背"Restrict OAuth scopes"这个词，而是让你看它真干活时怎么使。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

改配置

Restrict OAuth scopes

光知道意思还不够，这里得把规矩落进配置里，下面这块照着填。

{
  "mcpServers": {
    "slack": {
      "type": "http",
      "url": "https://mcp.slack.com/mcp",
      "oauth": {
        "scopes": "channels:read chat:write search:read"
      }
    }
  }
}

Use dynamic headers for custom authentication

这一段更像在讲判断条件，什么时候该上，什么时候先别急。把触发条件看清，比背标题更重要。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

改配置

Use dynamic headers for custom authentication 1

这会儿轮到改配置了，字段名和关键字别自己乱换。

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "/opt/bin/get-mcp-auth-headers.sh"
    }
  }
}

改配置

Use dynamic headers for custom authentication 2

这会儿轮到改配置了，字段名和关键字别自己乱换。

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "echo '{\"Authorization\": \"Bearer '\"$(get-token)\"'\"}'"
    }
  }
}

Add MCP servers from JSON configuration

这一段更像在讲判断条件，什么时候该上，什么时候先别急。把触发条件看清，比背标题更重要。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

改配置

Add MCP servers from JSON configuration 1

想把这条规矩固定住，就把下面这块老老实实写进去。

# Basic syntax
claude mcp add-json <name> '<json>'

# Example: Adding an HTTP server with JSON configuration
claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

# Example: Adding a stdio server with JSON configuration
claude mcp add-json local-weather '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}'

# Example: Adding an HTTP server with pre-configured OAuth credentials
claude mcp add-json my-server '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' --client-secret

终端里敲

Add MCP servers from JSON configuration 2

看到这里，别光点头，下面这条命令先跑起来再说。

claude mcp get weather-api

Import MCP servers from Claude Desktop

这一段更像在讲判断条件，什么时候该上，什么时候先别急。把触发条件看清，比背标题更重要。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

终端里敲

Import MCP servers from Claude Desktop 1

看到这里，别光点头，下面这条命令先跑起来再说。

# Basic syntax 
claude mcp add-from-claude-desktop

终端里敲

Import MCP servers from Claude Desktop 2

看到这里，别光点头，下面这条命令先跑起来再说。

claude mcp list

Use MCP servers from Claude.ai

这一段更像在讲判断条件，什么时候该上，什么时候先别急。把触发条件看清，比背标题更重要。

如果你打算把外接能力往里挂，这里提到的 hooks、MCP、skills、memory 都要分清各自负责哪一摊。

直接对 Claude 说

Use MCP servers from Claude.ai 1

到这里其实就剩一句话，把下面这句发出去就行。

/mcp

关键片段

Use MCP servers from Claude.ai 2

"Use MCP servers from Claude.ai"这一段里最要紧的原始写法在下面，先看它怎么落地。

ENABLE_CLAUDEAI_MCP_SERVERS=false claude

照着做一遍

第一次接 MCP，不要先碰最复杂的企业内网工具。

先接一个官方或公开可测的远程服务，把命令、连通、列服务这三步跑通。

终端里敲

第 1 步：先加一个 HTTP MCP 服务

HTTP 是现在最稳、最常见的接法。

claude mcp add --transport http notion https://mcp.notion.com/mcp

终端里敲

第 2 步：列一下你已经接上的服务

先确认它真的记住了，不要盲猜已经连上。

claude mcp list

直接对 Claude 说

第 3 步：进 Claude 里查状态

到了会话里，再看它是不是活着、工具是不是已经出现。

/mcp

直接对 Claude 说

第 4 步：先只做读，不要先做写

先让它查资料、读信息，等确认稳定了，再考虑改外部系统。

Use the connected MCP service to read available resources first.

一眼看懂这一页

这页的作用，就是把原本偏专业的话题，拆成能直接照着走的明白话。

模型上下文协议 (MCP)
   |
   v
模型上下文协议 (MCP) 这一页讲的，就是 模型上下文协议 (MCP) 这件事在 Claude Code 里到底怎么用。
   |
   v
照着步骤去做

文末提醒

这站会按官方 docs 的导航和内容变化继续重生成，原站加页、删页、改页时，这里会跟着更新。

人话解释会尽量顺着原页往下讲，但命令、参数名、配置名这些硬东西还是保留原样，免得你抄过去跑不起来。

顺手再看

Sub-agents、Plugins、MCP 怎么选

先分清 MCP 到底是接外线还是加功能。

MCP 连不上时先查什么

专门给 MCP 连接失败用的排错清单。