Python SDK 接入

Python SDK 当前发布版本为 mcp-sdk-py v0.1.5，需要 Python 3.11 或更高版本。SDK 会提供 Streamable HTTP、Gateway Token 校验、自注册、etcd lease、能力 manifest、/health 和 /metrics。

1. 安装脚手架并创建项目

SDK 位于公司私有 GitLab。先按内网规范配置 Git HTTP 凭据，再安装脚手架：

pipx install 'git+http://svrgit.dingtone.xyz/SRE/aiagentsteam/mcpplatform/mcpsdk/[email protected]'
mcp-server init my-mcp-server
cd my-mcp-server
python3 -m venv .venv
. .venv/bin/activate
pip install -e .
cp .env.example .env

2. 配置运行环境

在 .env 中填写实际部署环境的值。注册模式下不要配置 MCP_GATEWAY_TOKEN：SDK 会在启动时使用注册 Token 换取服务专属 Token。

MCP_SERVER_NAMESPACE=your-namespace
MCP_SERVER_NAME=my-mcp-server
MCP_SERVER_VERSION=0.1.0
MCP_SERVER_HOST=0.0.0.0
MCP_SERVER_PORT=18080
MCP_SERVER_PUBLIC_BASE_URL=http://<gateway-reachable-host>:18080
MCP_ETCD_ENDPOINTS=<etcd-host>:2379
MCP_ADMIN_BASE_URL=http://<admin-api-host>:<admin-api-port>
MCP_REGISTRATION_TOKEN=<registration-token-from-admin-ui>
MCP_LOG_LEVEL=INFO

MCP_SERVER_PUBLIC_BASE_URL 必须是 Gateway 能访问的地址，不是 Client 地址。生产环境将注册 Token 注入 Secret 或配置中心，不要写进镜像、源码或 Git。

3. 声明业务 Tool

脚手架生成的 server.py 已包含可运行示例。以最小查询 Tool 为例：

from mcp_sdk_py import BasicToolAuthorizer, McpRuntime, McpServer, RuntimeConfig, tool

server = McpServer(namespace="your-namespace", name="my-mcp-server", version="0.1.0")

@server.register
@tool(name="get_status", description="Query the current service status", access_type="read", risk_level="normal")
def get_status(service: str) -> dict[str, str]:
    return {"service": service, "status": "ok"}

McpRuntime(server, RuntimeConfig.from_env(), authorizer=BasicToolAuthorizer()).run()

生产服务必须继承 BasicToolAuthorizer 实现业务规则，例如限制查询范围、拒绝危险参数、校验操作对象和确认写操作。Tools、Resources 和 Prompts 的适用边界见 Tools、Resources 与 Prompts。

4. 启动与自注册

python server.py
curl http://127.0.0.1:18080/health

启动顺序为：调用 MCP_ADMIN_BASE_URL/admin/bootstrap/register-server 完成自注册，接收 Gateway-to-Server Token，然后以 60 秒 lease 向 etcd 注册实例和能力清单。注册成功后在平台服务列表检查实例；通过 Gateway 而非 SDK 端口验证 Tool。

5. 测试与上线

内网测试平台地址为 192.168.50.133。将测试环境实际发布的 Admin API、Gateway 和 etcd 地址填入配置后，按接入总览和仓库中的 mcp-docs/docs/手动测试-服务接入文档.md 完成验证。测试通过、能力 Review 和权限配置完成后，使用生产 namespace、Token、endpoint 和网络 ACL 部署上线。