apollo-mcp-server

Apollo MCP 服务指南

Apollo MCP 服务将 GraphQL 操作公开为 MCP 工具，使 AI Agent 能够通过 Model Context Protocol 与 GraphQL API 交互。

快速开始

步骤 1：安装

# Linux / MacOS
curl -sSL https://mcp.apollo.dev/download/nix/latest | sh

# Windows
iwr 'https://mcp.apollo.dev/download/win/latest' | iex

步骤 2：配置

在项目根目录中创建 config.yaml：

transport:
  type: streamable_http
schema:
  source: local
  path: ./schema.graphql
operations:
  source: local
  paths:
    - ./operations/
introspection:
  introspect:
    enabled: true
  search:
    enabled: true
  validate:
    enabled: true
  execute:
    enabled: true

启动服务：

apollo-mcp-server ./config.yaml

MCP 端点位于 http://127.0.0.1:8000/mcp（streamable_http 默认值：地址为 127.0.0.1，端口为 8000）。GraphQL 端点默认位于 http://localhost:4000/；如果 API 运行在其他位置，请使用 endpoint 键覆盖默认值。

服务会监视配置文件的更改，并自动使用更新后的配置重启。

步骤 3：连接

添加到 MCP 客户端配置中：

Streamable HTTP（推荐）：

Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "graphql-api": {
      "command": "npx",
      "args": ["mcp-remote", "http://127.0.0.1:8000/mcp"]
    }
  }
}

Claude Code：

claude mcp add graphql-api -- npx mcp-remote http://127.0.0.1:8000/mcp

Stdio（客户端直接启动服务）：

{
  "mcpServers": {
    "graphql-api": {
      "command": "./apollo-mcp-server",
      "args": ["./config.yaml"]
    }
  }
}

内置工具

工具	用途	使用时机
introspect	详细探索架构类型	需要类型定义、字段、关系时
search	在架构中查找类型	查找特定类型或字段时
validate	检查操作是否有效	执行操作之前
execute	运行临时 GraphQL 操作	测试或执行一次性查询时
explorer	在 Apollo Explorer 中打开操作	生成 Explorer URL（需要 GraphOS graph ref）

定义自定义工具

MCP 工具由 GraphQL 操作创建：

1. 操作文件（推荐）

operations:
  source: local
  paths:
    - ./operations/

2. 操作集合

operations:
  source: collection
  id: your-collection-id

3. 持久化查询

operations:
  source: manifest
  path: ./persisted-query-manifest.json

4. 架构内省

operations:
  source: introspect

5. GraphOS Uplink

operations:
  source: uplink

参考文件

• 工具 - 内省工具、explorer、minify 表示法、工具注解
• 配置 - 所有配置选项
• 身份验证 - OAuth 2.1、作用域、令牌验证、按操作配置作用域
• Rhai 脚本 - 生命周期钩子和内置函数
• MCP 提示词 - 可重复使用的提示词模板
• 遥测 - OpenTelemetry 指标、跟踪和仪表板
• 故障排除 - 常见问题及解决方案

关键规则

安全

安全：敏感操作。 在向 AI Agent 公开服务之前配置身份验证。使用 headers 配置 API 密钥，使用 OAuth 实现用户范围的访问。

• 在生产环境中禁用内省工具（默认已禁用）
• 使用 overrides.mutation_mode 控制 mutation 的公开方式

身份验证

# Static header
headers:
  Authorization: "Bearer ${env.API_TOKEN}"

# Dynamic header forwarding
forward_headers:
  - x-tenant-id

# OAuth (streamable_http transport)
transport:
  type: streamable_http
  auth:
    servers:
      - https://auth.example.com
    audiences:
      - https://api.example.com
    scopes:
      - read
    scope_mode: require_all

架构来源

# Local file
schema:
  source: local
  path: ./schema.graphql

# Federated graphs (uplink)
schema:
  source: uplink

# Non-federated graphs (graphos)
schema:
  source: graphos

Mutation

通过 overrides.mutation_mode 控制 mutation 行为：

模式	预定义 mutation	临时 mutation（execute）
none	跳过	拒绝
explicit	公开	拒绝
all	公开	允许

令牌优化

启用精简以减少令牌用量：

introspection:
  introspect:
    minify: true
  search:
    minify: true

常见模式

GraphOS 云端架构

graphos:
  apollo_key: ${env.APOLLO_KEY}
  apollo_graph_ref: my-graph@production
schema:
  source: uplink # federated graphs; use graphos for non-federated graphs

本地开发

transport:
  type: streamable_http
schema:
  source: local
  path: ./schema.graphql
introspection:
  introspect:
    enabled: true
  search:
    enabled: true
  validate:
    enabled: true
  execute:
    enabled: true
overrides:
  mutation_mode: all

生产环境设置

transport:
  type: streamable_http
  auth:
    servers:
      - https://auth.example.com
    audiences:
      - https://api.example.com
endpoint: https://api.production.com/graphql
operations:
  source: manifest
  path: ./persisted-query-manifest.json
graphos:
  apollo_key: ${env.APOLLO_KEY}
  apollo_graph_ref: ${env.APOLLO_GRAPH_REF}
schema:
  source: uplink # federated graphs; use graphos for non-federated graphs
health_check:
  enabled: true
telemetry:
  exporters:
    metrics:
      otlp:
        endpoint: https://your-metrics-endpoint
        protocol: http/protobuf
    tracing:
      otlp:
        endpoint: https://your-traces-endpoint
        protocol: http/protobuf

Docker

transport:
  type: streamable_http
  address: 0.0.0.0
  port: 8000
endpoint: ${env.GRAPHQL_ENDPOINT}
graphos:
  apollo_key: ${env.APOLLO_KEY}
  apollo_graph_ref: ${env.APOLLO_GRAPH_REF}
schema:
  source: uplink # federated graphs; use graphos for non-federated graphs
health_check:
  enabled: true

基本规则

• 在向 AI Agent 公开服务之前，始终配置身份验证
• 在共享环境中，始终使用 mutation_mode: explicit 或 mutation_mode: none
• 绝不向具有生产数据写入权限的环境公开内省工具
• 绝不将 auth 放在顶层；它必须嵌套在 transport 下
• 优先使用操作文件，而不是临时执行，以获得可预测的行为
• 在远程和多客户端部署中，优先使用 streamable_http 传输
• 对于非联邦架构，使用 schema.source: graphos（uplink 仅提供联邦架构）
• 仅当 MCP 客户端直接启动服务进程时，才使用 stdio
• 使用 GraphOS Studio 集合进行团队协作