Setting the file. One moment.
Subchapter 6.1
references/configuration.mdMarkdown8 KBView on GitHub
Apollo MCP Server uses YAML configuration. Pass the config file path as an argument:
apollo-mcp-server ./path/to/config.yamlThe GraphQL API endpoint URL. Defaults to http://localhost:4000/.
endpoint: https://api.example.com/graphqlSchema source configuration. Two options available:
schema:
source: local
path: ./schema.graphqluplink 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@productionDefine which GraphQL operations become MCP tools. Defaults to infer (auto-discovers from schema).
operations:
source: inferoperations:
source: local
paths:
- ./operations/**/*.graphqloperations:
source: collection
id: abc123-collection-idoperations:
source: manifest
path: ./persisted-query-manifest.jsonoperations:
source: uplinkConfigure how the MCP server communicates.
HTTP server for network access and multi-client deployments:
transport:
type: streamable_httpDefaults: address: 127.0.0.1, port: 8000. The MCP endpoint is served at http://127.0.0.1:8000/mcp.
| Option | Default | Description |
|---|---|---|
address | 127.0.0.1 | Bind address |
port | 8000 | Listen port |
stateful_mode | - | Session handling mode |
Controls which Host header values are accepted (streamable_http only):
transport:
type: streamable_http
host_validation:
enabled: true
allowed_hosts:
- "example.com"
- "*.example.com"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 | allStandard input/output for direct CLI integration. This is the default transport when no transport section is specified:
transport:
type: stdioNote: SSE transport was removed in v1.5.0. Use
streamable_httpinstead.
Configure HTTP headers for GraphQL requests.
headers:
Authorization: "Bearer ${env.API_TOKEN}"
X-API-Key: ${env.API_KEY}Forward headers from MCP client requests to the upstream GraphQL API:
forward_headers:
- x-forwarded-user-token
- x-request-idheaders:
Authorization: "Bearer ${env.API_TOKEN}"
forward_headers:
- x-user-context
- x-request-idControl 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: trueControl mutation behavior and other global settings.
overrides:
mutation_mode: explicit # all | explicit | none| Mode | Description |
|---|---|
all | Execute mutations directly |
explicit | Require user confirmation |
none | Block all mutations (default) |
Connect to Apollo GraphOS for managed schemas and operations.
graphos:
apollo_key: ${env.APOLLO_KEY}
apollo_graph_ref: my-graph@productiongraphos:
apollo_key: ${env.APOLLO_KEY}
apollo_graph_ref: ${env.APOLLO_GRAPH_REF}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:
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: 7200Health check is disabled by default. Applies to streamable_http transport only.
health_check:
enabled: true
path: /health # default| Option | Default | Description |
|---|---|---|
enabled | false | Enable health endpoint |
path | /health | Health check path |
Endpoints:
GET /health - Overall health: {"status": "UP"}GET /health?live - Liveness probeGET /health?ready - Readiness probelogging:
level: info # debug | info | warn | error
path: ./logs/mcp-server.log
rotation: dailytelemetry:
exporters:
metrics:
otlp:
endpoint: http://localhost:4317
tracing:
otlp:
endpoint: http://localhost:4317
service_name: graphql-mcp-serverUse ${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}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| Variable | Description |
|---|---|
APOLLO_KEY | GraphOS API key |
APOLLO_GRAPH_REF | Graph reference (graph@variant) |
schema:
source: local
path: ./schema.graphql
introspection:
introspect:
enabled: true
search:
enabled: true
validate:
enabled: true
execute:
enabled: true
overrides:
mutation_mode: alltransport:
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: truetransport:
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: explicitendpoint: 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