MCP 不是黑魔法——它是一层JSON-RPC 2.0 协议，规定 Claude（host） 和外部服务（server）之间该怎么互相说话。理解协议结构， 你就知道为什么会卡住、为什么会重连、为什么有的工具调一次反应慢。

架构层次

三种能力（Capability）

JSON-RPC 消息样例

// 1. Host 调用工具 → Server
{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "tools/call",
  "params": {
    "name": "query_database",
    "arguments": { "sql": "SELECT count(*) FROM users" }
  }
}

// 2. Server 响应 → Host
{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "content": [
      { "type": "text", "text": "42135" }
    ]
  }
}

// 3. Server 主动推送 → Host (notification, 无 id)
{
  "jsonrpc": "2.0",
  "method": "notifications/tools/list_changed"
}
// 表示工具列表更新——Claude 会重新拉取

Capability 协商流程

# 启动连接时,Host 与 Server 互相宣告能力

Host  → initialize: "我支持 tools, resources, sampling"
Server → initialized: "我提供 tools 与 resources, 不支持 sampling"
Host  → tools/list: "列一下你有什么工具"
Server → tools/list response: "[query_database, list_tables, ...]"

# 之后 Host 才会真正使用 Server 暴露的能力

Day 07 提到了三种 transport，但没说清楚怎么选。 transport 决定"在哪儿跑"，scope 决定"谁能用"——两个维度组合出生产环境的全部配置形态。

三种 transport 对比

三层 scope 优先级

添加 server 的命令

# 默认 local scope —— 仅你能用
$ claude mcp add my-tool -- npx my-mcp-server

# project scope —— 团队共享,生成 .mcp.json
$ claude mcp add database --scope project --transport stdio \
    -- npx -y @bytebase/dbhub --dsn "${DATABASE_URL}"

# user scope —— 你所有项目都生效
$ claude mcp add github --scope user --transport http \
    https://api.githubcopilot.com/mcp/ \
    --header "Authorization: Bearer ${GITHUB_TOKEN}"

# 查看每个 server 当前来自哪个 scope
$ claude mcp list --show-scope

敏感信息保护

99% 场景下你只需要这三类 MCP——查数据 / 改 issue / 发消息。 下面是每一类的最小可跑配置和典型用法。

集成 A · Postgres / 数据库

// .mcp.json — 接入只读数据库
{
  "mcpServers": {
    "db": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub"],
      "env": {
        // readonly 用户 + 只读副本
        "DB_DSN": "postgresql://readonly:${DB_PASS}@replica:5432/prod?sslmode=require"
      }
    }
  }
}

# 在 Claude Code 里你可以这样问:
> 用 db 服务器查一下 users 表里过去 7 天注册的人数
> 看一下 orders 表的 schema 然后写一个迁移脚本
> users 表上有哪些索引?有没有冗余的?

集成 B · GitHub PR / Issue

// 官方 GitHub Copilot MCP — http transport
{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${GITHUB_TOKEN}"
      }
    }
  }
}

# 典型用法:
> 把 PR #2398 的 description 读出来,然后总结这个 PR 的核心改动
> 创建一个 issue 标题为"修复登录页样式问题",label 加 frontend / bug
> 列出过去一周有 review 卡住的 PR,按等待时间排序

# Token 最小权限:
#   - repo:read 必需
#   - issues:write 看你需不需要写
#   - 永远别给 admin / delete 权限

集成 C · Slack 消息

// Slack MCP — 用于 Claude 主动通知 / 聚合频道消息
{
  "mcpServers": {
    "slack": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}",
        "SLACK_TEAM_ID": "${SLACK_TEAM_ID}"
      }
    }
  }
}

# 与 Day 10 的 Stop Hook 配合:
> 任务完成后,通过 slack MCP 给 #team-eng 频道发条消息说"PR 已合并"

# 跨频道聚合:
> 看一下 #incidents 频道过去 24 小时有哪些消息,
  按 P0/P1/P2 严重程度归类

三大集成的最佳协作

公司内部的 API、私有的工作流、特殊的内部系统—— 这些不会有现成 MCP server。好消息是：用 FastMCP（Python）或官方 SDK（TS） 30 行代码就能起一个。

Python · FastMCP 最小示例

# server.py
# pip install mcp[cli]

from mcp.server.fastmcp import FastMCP
import httpx

mcp = FastMCP("internal-api")

@mcp.tool()
def get_user_info(user_id: str) -> dict:
    """根据 user_id 从内部 API 查用户信息(包括订阅状态)。"""
    r = httpx.get(f"https://internal.api/users/{user_id}",
                  headers={"X-Token": os.getenv("API_TOKEN")})
    r.raise_for_status()
    return r.json()

@mcp.tool()
def trigger_report(user_id: str, report_type: str) -> str:
    """为指定用户触发一份后台报告生成任务。"""
    r = httpx.post("https://internal.api/reports",
                   json={"user_id": user_id, "type": report_type})
    return f"Report queued: {r.json()['job_id']}"

if __name__ == "__main__":
    mcp.run()

# 注册到 Claude Code (stdio 模式)
$ claude mcp add internal-api --scope local -- \
    python /path/to/server.py

# 验证连接
> /mcp
# 应该看到 internal-api: connected · 2 tools

# 直接调用
> 用 internal-api 的 get_user_info 查一下 user_id=12345 的信息

TypeScript · 官方 SDK 最小示例

// server.ts
// npm i @modelcontextprotocol/sdk zod

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "internal-api", version: "1.0.0",
});

server.registerTool("get_user_info", {
  description: "根据 user_id 查用户信息",
  inputSchema: { user_id: z.string() },
}, async ({ user_id }) => {
  const r = await fetch(`https://internal.api/users/${user_id}`);
  return { content: [{ type: "text", text: await r.text() }] };
});

await server.connect(new StdioServerTransport());

Resources（暴露文档/数据）示例

# Python · 暴露内部 wiki 作为 resources

@mcp.resource("wiki://{topic}")
def get_wiki(topic: str) -> str:
    """读取内部 Wiki 上指定主题的文档"""
    return wiki_client.fetch_page(topic)

# 在 Claude Code 中:
> 读一下 wiki://onboarding 然后帮我整理一份 PPT 大纲

本地开发与调试

MCP 让 Claude 能"动手"——意味着同样能动错。 把 MCP 接进生产前，下面这些防线必须先到位。

三类典型安全风险

五条防御铁律

读写分离的 MCP 配置

// 推荐: 同一个数据源拆成两个 MCP server
{
  "mcpServers": {
    // 1. 只读用 — 默认开启,任何场景都可用
    "db-readonly": {
      "type": "stdio",
      "env": { "DB_DSN": "postgresql://readonly:..." }
    },
    // 2. 写入用 — 默认禁用,只在显式需要时手动启用
    "db-write": {
      "type": "stdio",
      "env": { "DB_DSN": "postgresql://app:..." },
      "disabled": true   // ← 关键
    }
  }
}

# 用的时候临时启用:
> /mcp enable db-write
> 跑这条迁移脚本
> /mcp disable db-write   # 用完关掉

四个递进的实验——从接入第一个公共 MCP 到自建 server。 预计 50 分钟，每个 Lab 完成后用 /mcp 验证连接状态。

1. MCP 协议本质上基于哪个传输协议？三种 capability（Tools / Resources / Prompts）各自的语义是什么？
2. stdio / http / sse 三种 transport 各自最适合什么场景？给出选择口诀。
3. 三层 scope 的优先级是什么？带 admin 权限的 token 应该放哪一层？
4. 请用一句话说出三类典型 MCP 安全风险,以及对应的防御措施。
5. 用 FastMCP 写一个最小 server 至少需要哪几步？工具的描述从哪里来？