Define MCP Tools

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

• Local operation files

• Operation collections

• 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.

Define GraphQL operations for tools

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.

Introspection tools

In addition to defining specific tools for pre-defined GraphQL operations, Apollo MCP Server supports introspection tools that enable AI agents to explore the graph schema and execute operations dynamically.

You can enable the following introspection tools:

• introspect - allows the AI model to introspect the schema of the GraphQL API by providing a specific type name to get information about, and a depth parameter to determine how deep to traverse the subtype hierarchy. The AI model can start the introspection by looking up the top-level Query or Mutation type.

• search - allows the AI model to search for type information by providing a set of search terms. This can result in fewer tool calls than introspect, especially if the desired type is deep in the type hierarchy of the schema. Search results include all the parent type information needed to construct operations involving the matching type.

• validate - validates a GraphQL operation against the schema without executing it. This allows AI models to verify that their operations are syntactically correct and conform to the schema before execution, preventing unintended side effects. Operations should be validated prior to calling the execute tool.

• 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.

Minification

Both the introspect and search tools support minification of their results through the minify option. These options help optimize context window usage for AI models.

• Reduces context window usage: Minified GraphQL SDL takes up significantly less space in the AI model's context window, allowing for more complex schemas or additional context

• Uses compact notation: Type definitions use prefixed compact syntax and common scalar types are shortened

• Preserves functionality: All essential type information is retained, just in a more compact format

• Includes legend in tool descriptions: When minify is enabled, the tool descriptions automatically include a legend explaining the notation

Minification format:

• Type prefixes: T=type, I=input, E=enum, U=union, F=interface

• Scalar abbreviations: s=String, i=Int, f=Float, b=Boolean, d=ID

• Type modifiers: !=required, []=list, <>=implements

Example comparison:

Regular output:

1type User {
2  id: ID!
3  name: String
4  email: String!
5  posts: [Post]
6}

Minified output:

1T:User:id:d!,name:s,email:s!,posts:[Post]

1introspection:
2  execute:
3    enabled: true
4  introspect:
5    enabled: true
6    minify: true
7  search:
8    enabled: true
9    minify: true
10    index_memory_bytes: 50000000
11    leaf_depth: 1
12  validate:
13    enabled: true

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