apollo-mcp-server

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Apollo MCP Server Guide

Apollo MCP Server 使用指南

Apollo MCP Server exposes GraphQL operations as MCP tools, enabling AI agents to interact with GraphQL APIs through the Model Context Protocol.

Apollo MCP Server 将GraphQL操作暴露为MCP工具，使AI Agent能够通过Model Context Protocol与GraphQL API进行交互。

Quick Start

快速开始

Step 1: Install

步骤1：安装

bash

undefined

bash

undefined

Using npm

使用npm

npm install -g @apollo/mcp-server

Or run directly with npx

或直接用npx运行

npx @apollo/mcp-server

undefined

npx @apollo/mcp-server

undefined

Step 2: Configure

步骤2：配置

Create

mcp.yaml

in your project root:

yaml

undefined

在项目根目录创建

mcp.yaml

文件：

yaml

undefined

mcp.yaml

endpoint: https://api.example.com/graphql schema: type: local path: ./schema.graphql operations: type: local paths: - ./operations/**/*.graphql introspection: enabled: true

undefined

endpoint: https://api.example.com/graphql schema: type: local path: ./schema.graphql operations: type: local paths: - ./operations/**/*.graphql introspection: enabled: true

undefined

Step 3: Connect

步骤3：连接

Add to your MCP client configuration:

Claude Desktop (
claude_desktop_config.json
):

json

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

Claude Code (
.mcp.json
):

json

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

添加配置到你的MCP客户端：

Claude Desktop（
claude_desktop_config.json
）：

json

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

Claude Code（
.mcp.json
）：

json

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

Built-in Tools

内置工具

Apollo MCP Server provides four introspection tools:

Tool	Purpose	When to Use
`introspect`	Explore schema types in detail	Need type definitions, fields, relationships
`search`	Find types in schema	Looking for specific types or fields
`validate`	Check operation validity	Before executing operations
`execute`	Run ad-hoc GraphQL operations	Testing or one-off queries

Apollo MCP Server 提供四种自省工具：

工具	用途	适用场景
`introspect`	详细探索Schema类型	需要查看类型定义、字段、关联关系时
`search`	在Schema中查找类型	寻找特定类型或字段时
`validate`	检查操作的有效性	执行操作之前
`execute`	运行临时GraphQL操作	测试或一次性查询时

Defining Custom Tools

定义自定义工具

MCP tools are created from GraphQL operations. Three methods:

MCP工具通过GraphQL操作创建，有三种方式：

1. Operation Files (Recommended)

1. 操作文件（推荐）

yaml

operations:
  type: local
  paths:
    - ./operations/**/*.graphql

graphql

undefined

yaml

operations:
  type: local
  paths:
    - ./operations/**/*.graphql

graphql

undefined

operations/users.graphql

query GetUser($id: ID!) { user(id: $id) { id name email } }

mutation CreateUser($input: CreateUserInput!) { createUser(input: $input) { id name } }


Each named operation becomes an MCP tool.

query GetUser($id: ID!) { user(id: $id) { id name email } }

mutation CreateUser($input: CreateUserInput!) { createUser(input: $input) { id name } }


每个命名操作都会成为一个MCP工具。

2. Operation Collections

2. 操作集合

yaml

operations:
  type: collection
  id: your-collection-id

Use GraphOS Studio to manage operations collaboratively.

yaml

operations:
  type: collection
  id: your-collection-id

使用GraphOS Studio协作管理操作。

3. Persisted Queries

3. 持久化查询

yaml

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

For production environments with pre-approved operations.

yaml

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

适用于包含预批准操作的生产环境。

Reference Files

参考文档

Detailed documentation for specific topics:

Tools - Introspection tools and minify notation
Configuration - All configuration options
Troubleshooting - Common issues and solutions

特定主题的详细文档：

工具 - 自省工具与精简标记法
配置 - 所有配置选项
故障排查 - 常见问题与解决方案

Key Rules

核心规则

Security

安全

Never expose sensitive operations without authentication
Use
```
headers
```
configuration for API keys and tokens
Prefer
```
introspection.enabled: false
```
in production
Set
```
introspection.mutationMode: prompt
```
to require confirmation for mutations

切勿暴露敏感操作，除非已配置认证
使用
```
headers
```
配置项设置API密钥与令牌
生产环境中建议设置
```
introspection.enabled: false
```
设置
```
introspection.mutationMode: prompt
```
以要求对变更操作进行确认

Authentication

认证

yaml

undefined

yaml

undefined

Static header

静态请求头

headers: Authorization: "Bearer ${APOLLO_API_KEY}"

Dynamic header passthrough

动态请求头透传

headers: X-User-Token: from: x-forwarded-token

undefined

headers: X-User-Token: from: x-forwarded-token

undefined

Token Optimization

令牌优化

Enable minification to reduce token usage:

yaml

introspection:
  minify: true

Minified output uses compact notation:

T = type, I = input, E = enum
s = String, i = Int, b = Boolean, f = Float
! = required, [] = list

启用精简模式以减少令牌使用：

yaml

introspection:
  minify: true

精简后的输出使用紧凑标记：

T = 类型，I = 输入，E = 枚举
s = String，i = Int，b = Boolean，f = Float
! = 必填，[] = 列表

Mutations

变更操作

Control mutation behavior:

yaml

introspection:
  mutationMode: allowed   # Execute directly
  mutationMode: prompt    # Require confirmation (default)
  mutationMode: disabled  # Block all mutations

控制变更操作的行为：

yaml

introspection:
  mutationMode: allowed   # 直接执行
  mutationMode: prompt    # 需要确认（默认）
  mutationMode: disabled  # 阻止所有变更操作

Common Patterns

常见模式

GraphOS Cloud Schema

yaml

schema:
  type: uplink
graphos:
  key: ${APOLLO_KEY}
  graph_ref: my-graph@production

yaml

schema:
  type: uplink
graphos:
  key: ${APOLLO_KEY}
  graph_ref: my-graph@production

Local Development

本地开发

yaml

endpoint: http://localhost:4000/graphql
schema:
  type: local
  path: ./schema.graphql
introspection:
  enabled: true
  mutationMode: allowed

yaml

endpoint: http://localhost:4000/graphql
schema:
  type: local
  path: ./schema.graphql
introspection:
  enabled: true
  mutationMode: allowed

Production Setup

生产环境配置

yaml

endpoint: https://api.production.com/graphql
schema:
  type: uplink
operations:
  type: manifest
  path: ./persisted-query-manifest.json
introspection:
  enabled: false

yaml

endpoint: https://api.production.com/graphql
schema:
  type: uplink
operations:
  type: manifest
  path: ./persisted-query-manifest.json
introspection:
  enabled: false

Ground Rules

基本原则

ALWAYS configure authentication before exposing to AI agents
ALWAYS use
```
mutationMode: prompt
```
in shared environments
NEVER expose introspection tools with write access to production data
PREFER operation files over ad-hoc execute for predictable behavior
USE GraphOS Studio collections for team collaboration

在将服务暴露给AI Agent之前，务必配置认证
在共享环境中务必使用
```
mutationMode: prompt
```
切勿向生产数据暴露具有写入权限的自省工具
为了可预测的行为，优先使用操作文件而非临时execute操作
团队协作时使用GraphOS Studio集合