Command Reference

PREVIEW

This feature is in preview. Your questions and feedback are highly valued—don't hesitate to get in touch with your Apollo contact or post in the Apollo Community MCP Server Category.

Usage

Configure the Apollo MCP server with a YAML configuration file.

apollo-mcp-server [OPTIONS] <PATH/TO/CONFIG/FILE>

A configuration file is optional. If the file is not provided, environment variables for your graph credentials (APOLLO_GRAPH_REF and APOLLO_KEY) are required for the server to run.

CLI options

Option	Description
`-h, --help`	Print help information
`-V, --version`	Print version information

Example config file

The following example file sets your endpoint to localhost:4001, configures transport over Streamable HTTP, provides a GraphOS key and graph reference, enables introspection, and provides two local MCP operations for the server to expose.

YAML

1endpoint: http://localhost:4001/
2transport:
3  type: streamable_http
4graphos:
5  apollo_key: <YOUR_APOLLO_KEY>
6  apollo_graph_ref: <YOUR_APOLLO_GRAPH_REF>
7introspection:
8  introspect:
9    enabled: true
10operations:
11  source: local
12  paths:
13    - relative/path/to/your/operations/userDetails.graphql
14    - relative/path/to/your/operations/listing.graphql

Configuration options

All fields are optional.

Option	Type	Default	Description
`custom_scalars`	`FilePath`		Path to a custom scalar map
`endpoint`	`URL`	`http://localhost:4000/`	The target GraphQL endpoint
`graphos`	`GraphOS`		Apollo-specific credential overrides
`headers`	`Map<string, string>`	`{}`	List of hard-coded headers to include in all GraphQL requests
`health_check`	`HealthCheck`		Health check configuration
`introspection`	`Introspection`		Introspection configuration
`logging`	`Logging`		Logging configuration
`operations`	`OperationSource`		Operations configuration
`overrides`	`Overrides`		Overrides for server behavior
`schema`	`SchemaSource`		Schema configuration
`transport`	`Transport`		The type of server transport to use

GraphOS

These fields are under the top-level graphos key and define your GraphOS graph credentials and endpoints.

Option	Type	Description
`apollo_key`	`string`	The Apollo GraphOS key. You can also provide this with the `APOLLO_KEY` environment variable
`apollo_graph_ref`	`string`	The Apollo GraphOS graph reference. You can also provide this with the `APOLLO_GRAPH_REF` environment variable
`apollo_registry_url`	`URL`	The URL to use for Apollo's registry
`apollo_uplink_endpoints`	`URL`	List of uplink URL overrides. You can also provide this with the `APOLLO_UPLINK_ENDPOINTS` environment variable

Health checks

These fields are under the top-level health_check key.

Option	Type	Default	Description
`enabled`	`bool`	`false`	Enable health check endpoints
`path`	`string`	`"/health"`	Custom health check endpoint path
`readiness`	`object`		Readiness check configuration
`readiness.allowed`	`number`	`100`	Maximum number of rejections allowed in a sampling interval before marking unready
`readiness.interval`	`object`		Readiness check interval configuration
`readiness.interval.sampling`	`duration`	`"5s"`	How often to check the rejection count
`readiness.interval.unready`	`duration`	`"10s"`	How long to wait before recovering from unready state (default: 2 * sampling)

note

Health checks are only available when using the streamable_http transport. The health check feature is inspired by Apollo Router's health check implementation.

Introspection

These fields are under the top-level introspection key. Learn more about the MCP introspection tools.

Option	Type	Default	Description
`execute`	`object`		Execution configuration for introspection
`execute.enabled`	`bool`	`false`	Enable introspection for execution
`introspect`	`object`		Introspection configuration for allowing clients to run introspection
`introspect.enabled`	`bool`	`false`	Enable introspection requests
`introspect.minify`	`bool`	`false`	Minify introspection results to reduce context window usage
`search`	`object`		Search tool configuration
`search.enabled`	`bool`	`false`	Enable search tool
`search.index_memory_bytes`	`number`	`50000000`	Amount of memory used for indexing (in bytes)
`search.leaf_depth`	`number`	`1`	Depth of subtype information to include from matching types
`search.minify`	`bool`	`false`	Minify search results to reduce context window usage
`validate`	`object`		Validation tool configuration
`validate.enabled`	`bool`	`false`	Enable validation tool

Logging

These fields are under the top-level logging key.

Option	Type	Default	Description
`level`	`oneOf ["trace", "debug", "info", "warn", "error"]`	`"info"`	The minimum log level to record
`path`	`FilePath`		An output file path for logging. If not provided logging outputs to stdio/stderr.
`rotation`	`oneOf ["minutely", "hourly", "daily", "never"]`	`"hourly"`	The log file rotation interval (if file logging is used)

Operation source

These fields are under the top-level operations key. The available fields depend on the value of the nested source key. The default value for source is "infer".

Source	Option	Type	Default	Description
GraphOS Collection	`source`	`"collection"`		Load operations from a GraphOS collection
GraphOS Collection	`id`	`string`		The collection ID to use in GraphOS. Use `default` for the default collection. Learn more
Introspection	`source`	`"introspect"`		Load operations by introspecting the schema. Note: You must enable introspection to use this source
Local	`source`	`"local"`		Load operations from local GraphQL files or directories
Local	`paths`	`List<FilePath>`		Paths to GraphQL files or directories to search. Note: These paths are relative to the location from which you are running Apollo MCP Server.
Manifest	`source`	`"manifest"`		Load operations from a persisted queries manifest file
Manifest	`path`	`FilePath`		The path to the persisted query manifest
Uplink	`source`	`"uplink"`		Load operations from an uplink manifest. Note: This source requires an Apollo key and graph reference
Infer	`source`	`"infer"`	*	Infer where to load operations based on other configuration options.

Overrides

These fields are under the top-level overrides key.

Option	Type	Default	Description
`disable_type_description`	`bool`	`false`	Disable type descriptions to save on context-window space
`disable_schema_description`	`bool`	`false`	Disable schema descriptions to save on context-window space
`enable_explorer`	`bool`	`false`	Expose a tool that returns the URL to open a GraphQL operation in Apollo Explorer. Note: This requires a GraphOS graph reference
`mutation_mode`	`oneOf ["none", "explicit", "all"]`	`"none"`	Defines the mutation access level for the MCP server

Schema source

These fields are under the top-level schema key. The available fields depend on the value of the nested source key. The default value for source is "uplink".

Source	Option	Type	Default	Description
Local	`source`	`"local"`		Load schema from local file
Local	`path`	`FilePath`		Path to the GraphQL schema
Uplink	`source`	`"uplink"`	*	Fetch the schema from uplink. Note: This requires an Apollo key and graph reference

Transport

These fields are under the top-level transport key, to configure running the MCP Server in different environments - stdio, Streamable HTTP or SSE (deprecated).

Text

1transport:
2  type: stdio

The available fields depend on the value of the nested type key:

stdio (default)

Option	Value	Default Value	Description
`type`	`"stdio"`	*	Use standard IO for communication between the server and client

Streamable HTTP

Option	Value	Value Type	Description
`type`	`"streamable_http"`		Host the MCP server on the configuration, using streamable HTTP messages.
`address`	`127.0.0.1` (default)	`IpAddr`	The IP address to bind to
`port`	`5000` (default)	`u16`	The port to bind to

SSE (Deprecated, use StreamableHTTP)

Option	Value	Value Type	Description
`type`	`"sse"`		Host the MCP server on the supplied config, using SSE for communication. Deprecated in favor of `StreamableHTTP`
`address`	`127.0.0.1` (default)	`IpAddr`	The IP address to bind to
`port`	`5000` (default)	`u16`	The port to bind to

Auth

These fields are under the top-level transport key, nested under the auth key.

Option	Type	Description
`servers`	`List<URL>`	List of upstream delegated OAuth servers (must support OIDC metadata discovery endpoint)
`audiences`	`List<string>`	List of accepted audiences from upstream signed JWTs
`resource`	`string`	The externally available URL pointing to this MCP server. Can be `localhost` when testing locally.
`resource_documentation`	`string`	Optional link to more documentation relating to this MCP server
`scopes`	`List<string>`	List of queryable OAuth scopes from the upstream OAuth servers

Below is an example configuration using StreamableHTTP transport with authentication:

YAML

mcp.yaml

1transport:
2  type: streamable_http
3  auth:
4    # List of upstream delegated OAuth servers
5    # Note: These need to support the OIDC metadata discovery endpoint
6    servers:
7      - https://auth.example.com
8
9    # List of accepted audiences from upstream signed JWTs
10    # See: https://www.ory.sh/docs/hydra/guides/audiences
11    audiences:
12      - mcp.example.audience
13
14    # The externally available URL pointing to this MCP server. Can be `localhost`
15    # when testing locally.
16    # Note: Subpaths must be preserved here as well. So append `/mcp` if using
17    # Streamable HTTP or `/sse` is using SSE.
18    resource: https://hosted.mcp.server/mcp
19
20    # Optional link to more documentation relating to this MCP server.
21    resource_documentation: https://info.mcp.server
22
23    # List of queryable OAuth scopes from the upstream OAuth servers
24    scopes:
25      - read
26      - mcp
27      - profile

Run a local graph with MCP server using `rover dev`

You can use the rover dev command of Rover CLI v0.35 or later to run an Apollo MCP Server instance for local development alongside your local graph. Use the --mcp flag to start an MCP server and provide an optional configuration file.

1rover dev --mcp <PATH/TO/CONFIG>

Log Exporters

Metrics Exporters

Trace Exporters

Instrumentation

AWS Lattice