Apollo MCP Server User Guide

Here is the typical workflow for developing with Apollo MCP Server:

1. Install the MCP server.

2. Set up the graph that the MCP Server sits in front of.

3. Define the GraphQL operations to expose as MCP tools.

4. Configure and run your MCP Server.

5. Connect an MCP client and run the tools.

Set up graph

An Apollo MCP Server must know the schema of GraphQL API it supports. You can use either the schema option to provide the schema or graphos.apollo-graph-ref and graphos.apollo-key options to get the schema from uplink. If using schema option, it can be either an API or supergraph schema.

The schema is required for three main purposes:

1. Tool Descriptions: The schema provides type information used to generate tool descriptions. You can override these descriptions by adding comments to your operation files.

2. Input Validation: The schema is used to translate GraphQL input types into JSON Schema, ensuring that AI models provide correctly formatted inputs.

3. Introspection Support: If you enable the introspection option, the schema is used to provide information about available types and operations to AI models.

Define GraphQL operations for tools

You can manually define the GraphQL operations that are exposed by Apollo MCP Server as MCP tools. You can define these operations using:

• Operation files

• Persisted query manifests

• GraphOS-managed persisted queries

Alternatively, you can let an AI model read your graph schema via GraphQL introspection and have it determine the available operations.

From operation files

An operation file is a .graphql file containing a single GraphQL operation.

1query GetForecast($coordinate: InputCoordinate!) {
2  forecast(coordinate: $coordinate) {
3    detailed
4  }
5}

1query GetAllWeatherData($coordinate: InputCoordinate!, $state: String!) {
2  forecast(coordinate: $coordinate) {
3    detailed
4  }
5  alerts(state: $state) {
6    severity
7    description
8    instruction
9  }
10}

Use the operations option to provide the MCP Server with a list of operation files. For each operation file you provide, the MCP Server creates an MCP tool that calls the corresponding GraphQL operation.

You can also use the operations option to specify a directory. The server then loads all files with a .graphql extension in that directory as operations.

Files and directories specified with operations are hot reloaded. When you specify a file, the MCP tool is updated when the file contents are modified. When you specify a directory, operations exposed as MCP tools are updated when files are added, modified, or removed from the directory.

From Operation Collection

For graphs managed by GraphOS, Apollo MCP Server can get operations from an Operation Collection.

To use a GraphOS Operation Collection, you must:

• Set APOLLO_GRAPH_REF and APOLLO_KEY environment variables for a GraphOS graph

Each variant will have its own default MCP Tools Collection, but you can specify any shared collection by using operations with operations.source: collection. Apollo MCP Server automatically fetches the default collection if no ID is specified.

1operations:
2  source: collection
3  id: <collection-id>

The MCP Server supports hot reloading of the GraphOS Operation Collection, so it can automatically pick up changes from GraphOS without restarting.

From persisted query manifests

Apollo MCP Server supports reading GraphQL operations from Apollo-formatted persisted query manifest files.

Set the persisted query manifest file for the MCP Server with the operations option. The MCP Server supports hot reloading of persisted query manifests, so changes to manifests are applied without restarting.

An example manifest is available in the GitHub repo.

1headers:
2  'apollographql-client-name': 'my-web-app'
3operations:
4  source: manifest
5  path: <absolute path to this local repo>/graphql/weather/persisted_queries/apollo.json
6schema:
7  source: local
8  path: <absolute path to this local repo>/graphql/weather/api.graphql

apollo-mcp-server <path to the preceding config>

From GraphOS-managed persisted queries

For graphs managed by GraphOS, Apollo MCP Server can get operations by reading persisted queries from GraphOS. The MCP Server uses Apollo Uplink to access the persisted queries.

To use GraphOS persisted queries, you must:

• Set APOLLO_GRAPH_REF and APOLLO_KEY environment variables for a GraphOS graph

1headers:
2  'apollographql-client-name': 'my-web-app'
3operations:
4  source: uplink
5schema:
6  source: local
7  path: <absolute path to this git repo>/graphql/weather/api.graphql

1apollo-mcp-server <path to the preceding config>

The MCP Server supports hot reloading of GraphOS-managed persisted queries, so it can automatically pick up changes from GraphOS without restarting.

If you register a persisted query with a specific client name instead of null, you must configure the MCP Server to send the necessary header indicating the client name to the router.

Use the headers option when running the MCP Server to pass the header to the router. The default name of the header expected by the router is apollographql-client-name. To use a different header name, configure telemetry.apollo.client_name_header in router YAML configuration.

From schema introspection

For use cases where not all operations can be pre-defined, Apollo MCP Server supports tool creation based on introspection of the graph schema. This allows AI agents to explore a graph and execute operations dynamically.

To enable these schema-aware tools, run the MCP Server with the introspection option, which exposes two new tools:

• introspect - returns information about schema types

• execute - executes an operation on the GraphQL endpoint

The MCP client can use these tools to provide schema information to the model and its context window, and allow the model to execute GraphQL operations based on that schema.

1introspection:
2  execute:
3    enabled: true
4  introspect:
5    enabled: true

1apollo-mcp-server <path to the preceding config>

Deploying the MCP server

There are two ways to deploy and operate the MCP server.

1. Using the MCP server container or binary, which connects to an existing GraphQL API endpoint

2. Using the Apollo Runtime container, which includes both an MCP server as well as the Apollo router

Deploying the MCP server container

Apollo MCP Server is available as a standalone docker container. Container images are downloadable using the image ghcr.io/apollographql/apollo-mcp-server.

By default, the container expects all schema and operation files to be present in the /data folder within the container and that clients will use the Streamable HTTP transport on container port 5000.

An example docker run command that runs the MCP Server for the space dev example:

1endpoint: https://thespacedevs-production.up.railway.app/
2operations:
3  source: local
4  paths:
5  - /data/operations/
6schema:
7  source: local
8  path: /data/api.graphql

docker run \
  -it --rm \
  --name apollo-mcp-server \
  -p 5000:5000 \
  -v <path to the preceding config>:/config.yaml \
  -v $PWD/graphql/TheSpaceDevs:/data \
  ghcr.io/apollographql/apollo-mcp-server:latest /config.yaml

Deploying MCP using the Apollo Runtime container

The Apollo Runtime container includes all services necessary to serve GraphQL and MCP requests, including the Router and MCP Server. It is the easiest way to operate a GraphQL API with MCP support.

To serve both MCP and GraphQL requests, both port 4000 and 5000 will need to be exposed. An example command which retrieves the schema from Uplink is:

1docker run \
2  -p 4000:4000 \
3  -p 5000:5000 \
4  --env APOLLO_GRAPH_REF="<your-graph-ref>" \
5  --env APOLLO_KEY="<your-graph-api-key>" \
6  --env MCP_ENABLE=1 \
7  --rm \
8  ghcr.io/apollographql/apollo-runtime:latest

To learn more, review the Apollo Runtime container documentation.

Debugging with MCP Inspector

MCP Inspector is a debugging tool for MCP servers.

Debug locally over stdio transport

You can inspect a local Apollo MCP Server by running it with MCP Inspector.

1. Run the MCP Server with Inspector:

1operations:
2  source: local
3  paths:
4  - <absolute path to this git repo>/graphql/weather/operations/
5schema:
6  source: local
7  path: <absolute path to this git repo>/graphql/weather/api.graphql
8transport:
9  type: stdio

1npx @modelcontextprotocol/inspector \
2  target/debug/apollo-mcp-server <path to the preceding config>

Starting MCP inspector...
⚙️ Proxy server listening on port 6277
🔍 MCP Inspector is up and running at http://127.0.0.1:6274 🚀

1. In a browser, go to the URL returned by Inspector, then click Connect and List Tools. You should see the tools for the operations you provided.

Debug over the Streamable HTTP transport

When running the MCP Server over the Streamable HTTP transport, you can run MCP Inspector as follows.

1. Start the MCP Server in Streamable HTTP mode:

1operations:
2  source: local
3  paths:
4  - <absolute path to this git repo>/graphql/weather/operations/
5schema:
6  source: local
7  path: <absolute path to this git repo>/graphql/weather/api.graphql
8transport:
9  type: streamable_http
10  address: 127.0.0.1
11  port: 5000

1target/debug/apollo-mcp-server <path to the above config>

1. Start the MCP Inspector:

1npx @modelcontextprotocol/inspector

1. In a browser, go to the URL returned by Inspector, then fill in the details:

   • Transport Type: Select Streamable HTTP

   • URL: Enter http://127.0.0.1:5000/mcp, where the port must match the transport.port option

2. Click Connect and List Tools. You should see the tools for the operations you provided.

Custom scalars configuration

You can specify a custom scalars configuration JSON file to map a custom scalar to a JSON schema type. The JSON file is an object with custom scalar names as keys and JSON schema types as values:

1{
2  "MyCustomScalar": { "type": "string" }
3}

Other than JSON schema type, an overriding description can also be provided. In the following example the description provided in the schema, scalar description, would get overridden by the description found in the custom scalar configuration file, override description:

1"""
2scalar description
3"""
4scalar MyCustomScalar

1{
2  "MyCustomScalar": { "type": "string", "description": "override description" }
3}