---
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 |
| `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 |
### 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 | 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](/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 | 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).
```
transport:
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 |
| `stateful_mode` | `true` (default) | `bool` | Flag to enable or disable stateful mode and session management. |
##### 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. 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 Exporter` | `null` (Exporting disabled) | Configuration for exporting metrics via OTLP. |
| `omitted_attributes` | `List<String>` | | List of attributes to be omitted from metrics. |
#### Traces
| Option | Type | Default | Description |
| :-------------------- | :--------------- | :-------------------------- | :--------------------------------------------- |
| `otlp` | `OTLP 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 Exporter
| Option | Type | Default | Description |
| :--------- | :-------- | :-------------------------- | :--------------------------------------------------------------- |
| `endpoint` | `URL` | `http://localhost:4137` | URL to export data to. Requires full path. |
| `protocol` | `string` | `grpc` | Protocol for export. `grpc` and `http/protobuf` are supported. |
#### 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 file
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 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
```
## 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]'
```