MCP 入门与实战

MCP（Model Context Protocol，模型上下文协议）是 Anthropic 发起、现由 Linux 基金会托管的开放协议，为 LLM 与外部工具、数据源之间提供标准化的连接方式。截至 2026 年 5 月，MCP 生态已拥有 86K+ Star 的官方 Servers 仓库、10 种语言的 SDK，以及数千个社区开发的服务器。

本文介绍 MCP 的核心概念、在 OpenCode 中的配置方法，并以高德地图 MCP Server 为例进行实战演示。

什么是 MCP

在 MCP 出现之前，每个 AI 应用都需要为每个外部工具单独编写集成代码——A 应用接 GitHub 是一套，B 应用接 GitHub 是另一套，互不通用。

MCP 解决的核心问题是：一次编写，到处使用。任何实现了 MCP 协议的 Server，可以被任何 MCP 客户端（Claude Desktop、OpenCode、Cursor 等）直接使用。

graph TB
    Client["MCP Client<br/>Claude Desktop / OpenCode / Cursor / ..."]
    S1["Server A<br/>GitHub"]
    S2["Server B<br/>Files"]
    S3["Server C<br/>高德地图"]
    Client --- S1
    Client --- S2
    Client --- S3

MCP 的三种传输方式

在 OpenCode 中配置 MCP

本地 MCP Server

在 opencode.json 中配置，通过 command 指定启动命令：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-local-server": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/allowed"
      ],
      "enabled": true,
      "environment": {
        "MY_API_KEY": "your-key"
      }
    }
  }
}

1

"command": ["cmd", "/c", "npx", "-y", "my-mcp-command"]

远程 MCP Server

通过 URL 连接远程服务：

1
2
3
4
5
6
7
8
9
10
11

{
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}"
      }
    }
  }
}

OAuth 认证

部分远程 MCP Server 需要 OAuth 授权：

1

opencode mcp auth <server-name>

浏览器会自动打开完成授权流程，令牌存储在 ~/.local/share/opencode/mcp-auth.json。

工具级权限控制

MCP 暴露的工具可以和内置工具一样进行权限管理：

1
2
3
4
5
6

{
  "tools": {
    "my-mcp*": "ask",
    "dangerous-tool": false
  }
}

实战：高德地图 MCP Server

简介

amap-mcp-server 是一个基于高德地图 API 的 Python MCP Server，支持 stdio、SSE 和 Streamable HTTP 三种传输方式。提供 15+ 个工具，涵盖地理编码、路线规划、POI 搜索、天气查询等。

准备工作

1. 前往高德开放平台注册并创建应用
2. 在”应用管理”页面获取 API Key（选择 Web 服务类型）
3. 安装 uv（Python 包管理工具）：

1
2
3
4
5

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

在 OpenCode 中配置

在项目 opencode.json 中添加：

1
2
3
4
5
6
7
8
9
10
11
12
13

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "amap": {
      "type": "local",
      "command": ["uvx", "amap-mcp-server"],
      "enabled": true,
      "environment": {
        "AMAP_MAPS_API_KEY": "你的高德API Key"
      }
    }
  }
}

可用工具一览

地理编码：

路线规划：

POI 与天气：

使用示例

配置完成后，直接在 OpenCode 对话中使用：

场景一：出行规划

1

帮我查一下从"北京朝阳区阜通东大街6号"到"北京海淀区上地十街10号"怎么走？公交和驾车都告诉我。

Agent 自动调用 maps_direction_driving_by_address 和 maps_direction_transit_integrated_by_address 两个工具，返回完整的路线方案。

场景二：周边搜索

1

我在杭州西湖边上（120.15, 30.25），帮我找找附近 2 公里内有什么好吃的餐厅。

Agent 调用 maps_around_search，传入坐标和 keywords: "餐厅"。

场景三：天气查询

1

查一下深圳明天天气如何。

Agent 调用 maps_weather 获取天气数据。

场景四：多工具组合

1
2
3
4
5

我打算从上海坐高铁去南京玩，
帮我查一下：
1. 上海到南京的驾车距离
2. 夫子庙附近有什么酒店
3. 南京明天的天气

Agent 依次调用 maps_geo（解析”夫子庙”坐标）、maps_distance（驾车距离）、maps_around_search（夫子庙周边酒店）、maps_weather（南京天气）。

SSE 模式（远程部署）

如果需要在远程服务器上运行，可以使用 SSE 模式：

1
2

export AMAP_MAPS_API_KEY=你的API Key
uvx amap-mcp-server sse

客户端配置：

1
2
3
4
5
6
7
8

{
  "mcp": {
    "amap": {
      "type": "remote",
      "url": "http://your-server:8000/sse"
    }
  }
}

Streamable HTTP 模式

1
2

export AMAP_MAPS_API_KEY=你的API Key
uvx amap-mcp-server streamable-http

1
2
3
4
5
6
7
8

{
  "mcp": {
    "amap": {
      "type": "remote",
      "url": "http://your-server:8000/mcp"
    }
  }
}

官方参考 MCP Server

MCP 官方维护了一批参考实现，涵盖常见场景：

Filesystem 示例

让 AI 能安全地读写指定目录：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

{
  "mcp": {
    "filesystem": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/me/projects"
      ],
      "enabled": true
    }
  }
}

1

帮我看看 /Users/me/projects/my-app/package.json 里有哪些依赖需要升级

Memory 示例

跨会话保持上下文：

1
2
3
4
5
6
7
8

{
  "mcp": {
    "memory": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

社区热门 MCP Server

更多 MCP Server 可以在 MCP Registry 和 Smithery 上浏览。

MCP Server 的基本结构

一个最简单的 MCP Server 包含以下要素：

1
2
3
4
5
6
7
8
9
10
11
12

# server.py
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("My Server")

@mcp.tool()
def hello(name: str) -> str:
    """向指定名称问好"""
    return f"你好, {name}!"

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

运行：

1

uvx --from mcp my_server.py

核心要点：

1. @mcp.tool() 装饰器将普通函数暴露为 MCP Tool
2. 函数签名自动成为 Tool 的输入 schema（参数类型、描述）
3. docstring 自动成为 Tool 的描述，Agent 靠它判断何时调用
4. 三种原语可混合：一个 Server 可同时提供 Tools、Resources 和 Prompts

MCP vs Function Calling 对比

调试工具

MCP Inspector（官方可视化调试工具）：

1

npx @modelcontextprotocol/inspector uvx amap-mcp-server

浏览器打开后可以交互式测试每个 Tool，查看请求/响应详情。

参考链接

• MCP 官网
• MCP 规范
• 官方 Servers 仓库
• OpenCode MCP 配置文档
• 高德地图 MCP Server
• 高德开放平台
• MCP Registry