Apollo MCP Server

--- title: Config File Reference description: Reference guide of configuration options for running Apollo MCP Server. redirectFrom: - /apollo-mcp-server/command-reference --- You can configure Apollo MCP Server using a configuration file. You can also [override configuration options using environment variables](#override-configuration-options-using-environment-variables). See the [example config file](#example-config-file) for an example. ## Configuration options All fields are optional. ### Top-level options | Option | Type | Default | Description | | :--------------- | :-------------------- | :----------------------- | :--------------------------------------------------------------- | | `cors` | `Cors` | | CORS configuration | | `custom_scalars` | `FilePath` | | Path to a [custom scalar map](/apollo-mcp-server/custom-scalars) | | `endpoint` | `URL` | `http://localhost:4000/` | The target GraphQL endpoint | | `forward_headers`| `List<string>` | `[]` | Headers to forward from MCP clients to GraphQL API | | `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 | | `telemetry` | `Telemetry` | | Configuration to export metrics and traces via OTLP | ### GraphOS These fields are under the top-level `graphos` key and define your GraphOS graph credentials and endpoints. | Option | Type | Default | 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 | ### Static headers The `headers` option enables you to specify a list of static, hard-coded headers and values. These are included in all GraphQL requests. ```yaml title="mcp.yaml" headers: { "apollographql-client-name": "my-mcp-server" } ``` To forward dynamic header values from the client, use the [`forward_headers` option](#forwarding-headers) instead. ### Forwarding headers The `forward_headers` option allows you to forward specific headers from incoming MCP client requests to your GraphQL API. This is useful for: - Multi-tenant applications (forwarding tenant IDs) - A/B testing (forwarding experiment IDs) - Geo information (forwarding country codes) - Client identification (forwarding client names) - Internal instrumentation (forwarding correlation IDs) Header names should match exactly but are case-insensitive. Header values are forwarded as-is, according to what the MCP client provides. Hop-by-hop headers (like `connection`, `transfer-encoding`) are automatically blocked for security. ```yaml title="mcp.yaml" forward_headers: - x-tenant-id - x-experiment-id - x-geo-country ``` <Caution> Don't use header forwarding to pass through sensitive credentials such as API keys or access tokens. <br/><br/> According to [MCP security best practices](https://modelcontextprotocol.io/specification/2025-06-18/basic/security_best_practices#token-passthrough) and the [MCP authorization specification](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#access-token-privilege-restriction), token passthrough introduces serious security risks: - **Audience confusion**: If the MCP Server accepts tokens not intended for it, it can violate OAuth's trust boundaries. - **Confused deputy problem**: If an unvalidated token is passed downstream, a downstream API may incorrectly trust it as though it were validated by the MCP Server. <br/> Apollo MCP Server supports OAuth 2.1 authentication that follows best practices and aligns with the MCP authorization model. See our [authorization guide](/apollo-mcp-server/auth) for implementation details and how to use the [auth configuration](#auth). </Caution> ### CORS These fields are under the top-level `cors` key and configure Cross-Origin Resource Sharing (CORS) for browser-based MCP clients. | Option | Type | Default | Description | | :------------------ | :------------- | :---------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------- | | `enabled` | `bool` | `false` | Enable CORS support | | `origins` | `List<string>` | `[]` | List of allowed origins (exact matches). Use `["*"]` to allow any origin (not recommended in production) | | `match_origins` | `List<string>` | `[]` | List of regex patterns to match allowed origins (e.g., `"^https://localhost:[0-9]+$"`) | | `allow_any_origin` | `bool` | `false` | Allow requests from any origin. Cannot be used with `allow_credentials: true` | | `allow_credentials` | `bool` | `false` | Allow credentials (cookies, authorization headers) in CORS requests | | `allow_methods` | `List<string>` | `["GET", "POST", "OPTIONS"]` | List of allowed HTTP methods | | `allow_headers` | `List<string>` | `["content-type", "mcp-protocol-version", "mcp-session-id", "traceparent", "tracestate"]` | List of allowed request headers | | `expose_headers` | `List<string>` | `["mcp-session-id", "traceparent", "tracestate"]` | List of response headers exposed to the browser (includes MCP and W3C Trace Context headers) | | `max_age` | `number` | `86400` | Maximum age (in seconds) for preflight cache | ### Health checks These fields are under the top-level `health_check` key. Learn more about [health checks](/apollo-mcp-server/health-checks). | 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. </Note> ### Introspection These fields are under the top-level `introspection` key. Learn more about the MCP [introspection tools](/apollo-mcp-server/define-tools#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"`. Learn more about [defining tools as operations](/apollo-mcp-server/define-tools). | Source | Option | Type | 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](/apollo-mcp-server/define-tools#from-operation-collection). | | 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 | 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). ```yaml transport: type: streamable_http address: 127.0.0.1 port: 5000 stateful_mode: true ``` ##### Type The available fields depend on the value of the nested `type` key. The default type is `stdio`: | Option | Description | | :-------------------- | :--------------------------------------------------------------------------------------------------------------- | | `"stdio"` | Use standard IO for communication between the server and client | | `"streamable_http"` | Host the MCP server on the configuration, using streamable HTTP messages | | `"sse"` | Host the MCP server on the supplied config, using SSE for communication. Deprecated in favor of `StreamableHTTP` | ##### Transport Type Specific options Some transport types support further configuration. For both `streamable_http` and `sse`, you can set the `address` and `port`. For `streamable_http`, you can also set `stateful_mode`. | Option | Type | Default | Description | | :-------------- | :--------- | :---------- | :----------------------------------------------------------------------------------- | | `address` | `IpAddr` | `127.0.0.1` | The IP address to bind to | | `port` | `u16` | `8000` | The port to bind to | | `stateful_mode` | `bool` | `true` | Flag to enable or disable stateful mode and session management. Not supported by SSE | <Note> For Apollo MCP Server `≤v1.0.0`, the default `port` value is `5000`. In `v1.1.0`, the default `port` option was changed to `8000` to avoid conflicts with common development tools and services that typically use port 5000 (such as macOS AirPlay, Flask development servers, and other local services). </Note> ### Auth These fields are under the top-level `transport` key, nested under the `auth` key. Learn more about [authorization and authentication](/apollo-mcp-server/auth). | Option | Type | Default | 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 | | `disable_auth_token_passthrough` | `bool` | `false` | Optional flag to disable passing validated Authorization header to downstream API | Below is an example configuration using `StreamableHTTP` transport with authentication: ```yaml title="mcp.yaml" transport: type: streamable_http auth: # List of upstream delegated OAuth servers # Note: These need to support the OIDC metadata discovery endpoint servers: - https://auth.example.com # List of accepted audiences from upstream signed JWTs # See: https://www.ory.sh/docs/hydra/guides/audiences audiences: - mcp.example.audience # The externally available URL pointing to this MCP server. Can be `localhost` # when testing locally. # Note: Subpaths must be preserved here as well. So append `/mcp` if using # Streamable HTTP or `/sse` is using SSE. resource: https://hosted.mcp.server/mcp # Optional link to more documentation relating to this MCP server. resource_documentation: https://info.mcp.server # List of queryable OAuth scopes from the upstream OAuth servers scopes: - read - mcp - profile ``` ### Telemetry | Option | Type | Default | Description | | :-------------- | :---------- | :-------------------------- | :--------------------------------------- | | `service_name` | `string` | "apollo-mcp-server" | The service name in telemetry data. | | `version` | `string` | Current crate version | The service version in telemetry data. | | `exporters` | `Exporters` | `null` (Telemetry disabled) | Configuration for telemetry exporters. | #### Exporters | Option | Type | Default | Description | | :--------- | :---------- | :-------------------------- | :--------------------------------------- | | `metrics` | `Metrics` | `null` (Metrics disabled) | Configuration for exporting metrics. | | `tracing` | `Tracing` | `null` (Tracing disabled) | Configuration for exporting traces. | #### Metrics | Option | Type | Default | Description | | :-------------------- | :---------------------- | :-------------------------- | :--------------------------------------------- | | `otlp` | `OTLP Metric Exporter` | `null` (Exporting disabled) | Configuration for exporting metrics via OTLP. | | `omitted_attributes` | `List<String>` | | List of attributes to be omitted from metrics. | #### OTLP Metrics Exporter | Option | Type | Default | Description | |:--------------|:-----------------------------------------------|:------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `endpoint` | `URL` | `http://localhost:4317` | URL to export data to. Requires full path. | | `protocol` | `string` | `grpc` | Specifies the export protocol. Supported values are `grpc` and `http/protobuf`. | | `temporality` | `MetricTemporality` | `Cumulative` | Specifies how additive quantities are expressed over time. `Cumulative` means reported values include previous measurements, and `Delta` means they don't. | | `metadata` | Key-value pairs | | Key-value pairs for metadata. This field applies only when `protocol` is `grpc`. | | `headers` | Key-value pairs | | Key-value pairs for headers. This field applies only when `protocol` is `http/protobuf`. | <ExpansionPanel title="Metrics telemetry config example using gRPC"> The following example configures metrics telemetry to use the `grpc` protocol and sends data to the `http://localhost:4317` endpoint. It includes metadata with each request. ```yaml config.yaml telemetry: exporters: metrics: otlp: endpoint: http://localhost:4317 protocol: grpc temporality: cumulative metadata: key-name: some-value key-two: another-value ``` For observability platforms that prefer delta temporality (such as New Relic), configure the temporality and pass your API key via metadata: ```yaml config.yaml telemetry: exporters: metrics: otlp: endpoint: https://otlp.nr-data.net:4317 protocol: grpc temporality: delta metadata: api-key: <YOUR_API_KEY> ``` To use environment variables for sensitive values like API keys: ```sh export APOLLO_MCP_TELEMETRY__EXPORTERS__METRICS__OTLP__METADATA__API_KEY="${YOUR_API_KEY}" ``` </ExpansionPanel> #### Traces | Option | Type | Default | Description | | :-------------------- | :--------------------- | :-------------------------- | :--------------------------------------------- | | `otlp` | `OTLP Trace Exporter` | `null` (Exporting disabled) | Configuration for exporting traces via OTLP. | | `sampler` | `SamplerOption` | `ALWAYS_ON` | Configuration to control sampling of traces. | | `omitted_attributes` | `List<String>` | | List of attributes to be omitted from traces. | #### OTLP Trace Exporter | Option | Type | Default | Description | |:-------------|:---------------------------------------------|:------------------------|:-----------------------------------------------------------------------------------------| | `endpoint` | `URL` | `http://localhost:4317` | URL to export data to. Requires full path. | | `protocol` | `string` | `grpc` | Specifies the export protocol. Supported values are `grpc` and `http/protobuf`. | | `metadata` | Key-value pairs | | Key-value pairs for metadata. This field applies only when `protocol` is `grpc`. | | `headers` | Key-value pairs | | Key-value pairs for headers. This field applies only when `protocol` is `http/protobuf`. | <ExpansionPanel title="Tracing telemetry config example using HTTP/Protobuf"> The following example section configures tracing telemetry to use the `http/protobuf` protocol and sends data to the `http://localhost:4317` endpoint. It also includes headers with each request. ```yaml config.yaml telemetry: exporters: tracing: otlp: endpoint: http://localhost:4317 protocol: http/protobuf headers: key-name: some-value key-two: another-value ``` </ExpansionPanel> #### MetricTemporality | Option | Type | Description | |:-------------|:------------|:-------------------------------| | `cumulative` | `string` | Cumulative temporality option. | | `delta` | `string` | Delta temporality option. | | `lowmemory` | `string` | Low memory temporality option. | #### SamplerOption | Option | Type | Description | | :----------- | :-------- | :------------------------------------------------------- | | `always_on` | `string` | All traces will be exported. | | `always_off` | `string` | Sampling is turned off, no traces will be exported. | | `0.0-1.0` | `f64` | Percentage of traces to export. | ## Example config files The following example file sets your endpoint to `localhost:4001`, configures transport over Streamable HTTP, enables introspection, and provides two local MCP operations for the server to expose. ```yaml title="config.yaml" endpoint: http://localhost:4001/ transport: type: streamable_http introspection: introspect: enabled: true operations: source: local paths: - relative/path/to/your/operations/userDetails.graphql - relative/path/to/your/operations/listing.graphql ``` This configuration file will set up Streamable HTTP transport, enables introspection, and makes all operations derive from introspection: ```yaml title="config.yaml" transport: type: streamable_http introspection: introspect: enabled: true operations: source: introspect ``` ## Override configuration options using environment variables You can override configuration options using environment variables. The environment variable name is the same as the option name, but with `APOLLO_MCP_` prefixed. You can use `__` to mark nested options. For example, to override the `introspection.execute.enabled` option, you can set the `APOLLO_MCP_INTROSPECTION__EXECUTE__ENABLED` environment variable. ```sh APOLLO_MCP_INTROSPECTION__EXECUTE__ENABLED="true" ``` For list values, you can set the environment variable to a comma-separated list. For example, to override the `transport.auth.servers` option, you can set the `APOLLO_MCP_TRANSPORT__AUTH__SERVERS` environment variable to a comma-separated list. ```sh APOLLO_MCP_TRANSPORT__AUTH__SERVERS='[server_url_1,server_url_2]' ```