文档开发者接入

MCP 工具接入、配置与验证

公开当前配置结构,说明 stdio / HTTP 接入、工具 schema 和授权要求。

MCP 的职责

MCP 用于发现和调用外部工具及资源,不替代业务身份、应用授权或人工审批。当前客户端源码有 stdio 与 HTTP 传输实现。工具描述、只读标注和返回文本来自连接服务,本身不能作为获得执行权限的依据。具体协议版本与能力需在握手及联调中确认。

本地 stdio 配置示例

以下配置形状与当前解析器一致;命令和脚本为占位示例,需先安装并审查实际服务。command 是程序路径,args 是参数数组,不作为拼接的 shell 命令使用。使用运行账户所需的最小目录权限,避免通过环境变量扩大运行范围。

json
{
  "transport": "stdio",
  "command": "/absolute/path/to/node",
  "args": [
    "/absolute/path/to/read-only-connector.mjs"
  ],
  "env": {}
}

远程 HTTP 配置示例

示例域名不会提供服务。当前配置要求远程使用 HTTPS;HTTP 只允许本机回环地址。URL 不允许用户名、密码、查询串或片段,凭据按受控配置放入 headers。示例占位值不会自动读取环境变量;生产密钥应通过管理员认可的安全方式填写和轮换。

json
{
  "transport": "http",
  "url": "https://connector.example.invalid/mcp",
  "headers": {
    "Authorization": "Bearer REPLACE_WITH_SCOPED_TOKEN"
  }
}

当前配置约束

当前解析器也接受只含一个服务的 mcpServers 包装结构,一次添加一个服务。未知字段会被拒绝,整体配置不超过 64,000 字节;args 不超过 64 项,env 或 headers 不超过 32 项。不要把其他客户端的整份配置原样导入,特别是带有额外启动选项的配置。

工具 schema 与结果约定

工具用明确名称、说明和 JSON Schema 描述输入,限制可接受字段和数据量。返回结构化业务结果或明确错误,注明来源、捕获时间与完整性。以下是第三方服务可实现的只读工具描述示例,不是已提供的内置工具。readOnlyHint 是提示,权限仍由接入与执行策略控制。

json
{
  "name": "lookup_order",
  "description": "Read one order from the authorized store.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "orderId": {
        "type": "string",
        "minLength": 1,
        "maxLength": 120
      }
    },
    "required": [
      "orderId"
    ],
    "additionalProperties": false
  },
  "annotations": {
    "readOnlyHint": true
  }
}

从发现到实际执行的验收

依次检查服务启动、协议握手、工具枚举、无敏感样本调用、越权拒绝、断连恢复和凭据撤销。记录服务与客户端版本、工具名、输入摘要及结果证据。配置状态和工具数量只说明发现进度,必须看到真实调用结果才能确认链路可用。

返回全部文档下一篇指南

还有疑问?

查看专家支持