/apollo-mcp-server

Apollo MCP Server Configuration Reference

Table of Contents

• Configuration File
• Core Settings
  • endpoint
  • schema
  • operations
• Transport
• Headers
• Introspection
• Overrides
• GraphOS Integration
• Advanced Settings
• Environment Variables
• Configuration Examples

Configuration File

Apollo MCP Server uses YAML configuration. Pass the config file path as an argument:

apollo-mcp-server ./path/to/config.yaml

Core Settings

endpoint

The GraphQL API endpoint URL. Defaults to http://localhost:4000/.

endpoint: https://api.example.com/graphql

schema

Schema source configuration. Two options available:

Local File

schema:
  source: local
  path: ./schema.graphql

GraphOS Uplink (Default)

uplink is the default schema source. When using uplink, you can omit the schema section entirely if graphos credentials are configured.

schema:
  source: uplink
graphos:
  apollo_key: ${env.APOLLO_KEY}
  apollo_graph_ref: my-graph@production

operations

Define which GraphQL operations become MCP tools. Defaults to infer (auto-discovers from schema).

Infer (Default)

operations:
  source: infer

Local Files

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

GraphOS Collection

operations:
  source: collection
  id: abc123-collection-id

Persisted Query Manifest

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

GraphOS Uplink

operations:
  source: uplink

Transport

Configure how the MCP server communicates.

Streamable HTTP

HTTP server for network access and multi-client deployments:

transport:
  type: streamable_http

Defaults: address: 127.0.0.1, port: 8000. The MCP endpoint is served at http://127.0.0.1:8000/mcp.

Host Validation

Controls which Host header values are accepted (streamable_http only):

transport:
  type: streamable_http
  host_validation:
    enabled: true
    allowed_hosts:
      - "example.com"
      - "*.example.com"

Auth

OAuth-based authentication for streamable_http transport:

transport:
  type: streamable_http
  auth:
    servers:
      - https://auth.example.com/.well-known/openid-configuration
    audiences:
      - https://api.example.com
    scopes:
      - read
      - write
    scope_mode: any  # any | all

Stdio (Default)

Standard input/output for direct CLI integration. This is the default transport when no transport section is specified:

transport:
  type: stdio

Note: SSE transport was removed in v1.5.0. Use streamable_http instead.

Headers

Configure HTTP headers for GraphQL requests.

Static Headers

headers:
  Authorization: "Bearer ${env.API_TOKEN}"
  X-API-Key: ${env.API_KEY}

Dynamic Header Forwarding

Forward headers from MCP client requests to the upstream GraphQL API:

forward_headers:
  - x-forwarded-user-token
  - x-request-id

Combined

headers:
  Authorization: "Bearer ${env.API_TOKEN}"
forward_headers:
  - x-user-context
  - x-request-id

Introspection

Control built-in introspection tools. All tools are disabled by default.

introspection:
  introspect:
    enabled: true
    minify: true
  search:
    enabled: true
    minify: true
  validate:
    enabled: true
  execute:
    enabled: true

Overrides

Control mutation behavior and other global settings.

overrides:
  mutation_mode: explicit  # all | explicit | none

Mutation Modes

GraphOS Integration

Connect to Apollo GraphOS for managed schemas and operations.

graphos:
  apollo_key: ${env.APOLLO_KEY}
  apollo_graph_ref: my-graph@production

With Uplink Schema

graphos:
  apollo_key: ${env.APOLLO_KEY}
  apollo_graph_ref: ${env.APOLLO_GRAPH_REF}

Advanced Settings

Custom Scalars

Define how custom scalars are described to AI agents via an external JSON file:

custom_scalars: ./scalars.json

// scalars.json
{
  "DateTime": "ISO 8601 date-time string (e.g. 2024-01-15T10:30:00Z)",
  "JSON": "Arbitrary JSON object",
  "UUID": "UUID v4 string (e.g. 550e8400-e29b-41d4-a716-446655440000)"
}

CORS (Streamable HTTP Transport)

cors:
  enabled: true
  origins:
    - http://localhost:3000
    - https://app.example.com
  # OR use match_origins for regex pattern matching:
  # match_origins:
  #   - "^https://([a-z0-9]+[.])*example.com$"
  # OR allow all origins (cannot be used with allow_credentials):
  # allow_any_origin: true
  allow_credentials: true
  allow_methods:
    - GET
    - POST
  allow_headers:
    - accept
    - content-type
    - mcp-protocol-version
    - mcp-session-id
  expose_headers:
    - mcp-session-id
  max_age: 7200

Health Check

Health check is disabled by default. Applies to streamable_http transport only.

health_check:
  enabled: true
  path: /health  # default

Endpoints:

• GET /health - Overall health: {"status": "UP"}
• GET /health?live - Liveness probe
• GET /health?ready - Readiness probe

Logging

logging:
  level: info  # debug | info | warn | error
  path: ./logs/mcp-server.log
  rotation: daily

Telemetry

telemetry:
  exporters:
    metrics:
      otlp:
        endpoint: http://localhost:4317
    tracing:
      otlp:
        endpoint: http://localhost:4317
  service_name: graphql-mcp-server

Environment Variables

Config File Expansion

Use ${env.VAR_NAME} syntax inside YAML config files to reference environment variables:

endpoint: ${env.GRAPHQL_ENDPOINT}
headers:
  Authorization: "Bearer ${env.API_TOKEN}"
graphos:
  apollo_key: ${env.APOLLO_KEY}

Environment Variable Overrides

Any config option can be overridden via environment variables using the APOLLO_MCP_ prefix with __ (double underscore) as the nesting separator:

# Override transport type
export APOLLO_MCP_TRANSPORT__TYPE=streamable_http

# Override transport port
export APOLLO_MCP_TRANSPORT__PORT=9000

# Override logging level
export APOLLO_MCP_LOGGING__LEVEL=debug

GraphOS Variables

Configuration Examples

Minimal Local Development

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

Production with GraphOS

transport:
  type: streamable_http
endpoint: ${env.GRAPHQL_ENDPOINT}
operations:
  source: manifest
  path: ./persisted-query-manifest.json
graphos:
  apollo_key: ${env.APOLLO_KEY}
  apollo_graph_ref: ${env.APOLLO_GRAPH_REF}
headers:
  Authorization: "Bearer ${env.API_TOKEN}"
health_check:
  enabled: true

Team Development

transport:
  type: streamable_http
endpoint: https://dev-api.example.com/graphql
schema:
  source: local
  path: ./schema.graphql
operations:
  source: local
  paths:
    - ./operations/**/*.graphql
headers:
  Authorization: "Bearer ${env.DEV_API_TOKEN}"
introspection:
  introspect:
    enabled: true
    minify: true
  search:
    enabled: true
    minify: true
  validate:
    enabled: true
  execute:
    enabled: true
overrides:
  mutation_mode: explicit

Read-Only Analytics

endpoint: https://analytics.example.com/graphql
schema:
  source: local
  path: ./analytics-schema.graphql
operations:
  source: local
  paths:
    - ./queries/**/*.graphql
introspection:
  introspect:
    enabled: true
  search:
    enabled: true
  validate:
    enabled: true