# Apollo MCP Server An MCP Server to expose a pre-defined set of GraphQL operations as MCP tools. Optionally provides introspection tools to allow an LLM to generate and execute its own ad hoc operations. # Running the Example The repo has an example schema in `graphql/weather/weather.graphql`, and an example set of operations in `graphql/weather/operations/*.graphql`. First, build the repo with: ```sh cargo build ``` Next, run the graph in the Apollo Router: ```sh rover dev --supergraph-config ./graphql/weather/supergraph.yaml ``` ## MCP Inspector You can run the MCP Server with [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector). ### Stdio Transport You can run the MCP inspector with the stdio transport as follows: ```sh npx @modelcontextprotocol/inspector \ target/debug/apollo-mcp-server \ --directory \ -s graphql/weather/api.graphql \ -o graphql/weather/operations/forecast.graphql graphql/weather/operations/alerts.graphql graphql/weather/operations/all.graphql ``` Press "Connect" in the MCP Inspector and "List Tools" to see the list of available tools. ### HTTP+SSE Transport To use the SSE transport with MCP Inspector, first start the MCP server in SEE mode: ```sh target/debug/apollo-mcp-server \ --directory \ --sse-port 5000 -s graphql/weather/api.graphql \ -o graphql/weather/operations/forecast.graphql graphql/weather/operations/alerts.graphql graphql/weather/operations/all.graphql ``` Now start the MCP Inspector: ```sh npx @modelcontextprotocol/inspector ``` Set the transport to SSE in the inspector and the URL to `http://localhost:5000/sse`, then press "Connect" in MCP Inspector. ## MCP Client You can use the MCP Server with your favorite MCP client. ### Client Configuration For Claude Desktop, the configuration file is in the following location on MacOS: ```sh ~/Library/Application\ Support/Claude/claude_desktop_config.json ``` For Cursor, you can find the file by opening the MCP tab in Settings. #### Stdio Transport To use the stdio transport, add the following to the MCP configuration file for you client, using the absolute path to this Git repo: ```json { "mcpServers": { "weather": { "command": "/target/debug/apollo-mcp-server", "args": [ "--directory", "", "--schema", "graphql/weather/api.graphql", "--operations", "graphql/weather/operations/forecast.graphql", "graphql/weather/operations/alerts.graphql", "graphql/weather/operations/all.graphql" ] } } } ``` #### HTTP+SEE Transport To use the HTTP+SSE transport, first start the MCP server as described above for MCP Inspector. For Claude Desktop, you can use [`mcp-remote`](https://www.npmjs.com/package/mcp-remote/v/latest?activeTab=readme) to give Claude access to the MCP Server over SSE: ```json { "mcpServers": { "weather": { "command": "npx", "args": [ "mcp-remote", "http://127.0.0.1:5000/sse", "--transport", "sse-first" ] } } } ``` For Cursor, you can directly specify the SSE URL: ```json { "mcpServers": { "weather": { "url": "http://127.0.0.1:5000/sse" } } } ``` ### Usage Restart your AI agent. You should now see the tools successfully registered. For example, in Claude Desktop, you should see a small hammer icon with the number of tools next to it. You can now issue prompts related to weather forecasts and alerts, which will call out to the tools and invoke the GraphQL operations. **Note** that due to current limitations of Apollo Connectors, the schema is using a hard-coded weather forecast link, so the forecast will be for a fixed location. #### Persisted Queries Manifests The MCP server also supports reading operations from an [Apollo](https://www.apollographql.com/docs/graphos/platform/security/persisted-queries#manifest-format) formatted persisted query manifest file through the use of the `--manifest` flag. An example is included in `graphql/weather/persisted_queries`. ```sh target/debug/apollo-mcp-server \ --directory \ -s graphql/weather/api.graphql \ --header "apollographql-client-name:my-web-app" \ --manifest graphql/weather/persisted_queries/apollo.json ``` Note that when using persisted queries, if your queries are registered with a specific client name instead of `null`, you will need to configure the MCP server to send the necessary header indicating the client name to the router. This header is `apollographql-client-name` by default, but can be overridden in the router config by setting `telemetry.apollo.client_name_header`. Note that in the example persisted query manifest file, the client name is `my-web-app`. This supports hot-reloading, so changes to the persisted query manifest file will be picked up by the MCP server without restarting. #### Uplink The MCP server can also read persisted queries from Uplink using the `--uplink` option. This supports hot-reloading, so it will pick up changes from GraphOS automatically, without restarting the MCP server. You must set the `APOLLO_KEY` and `APOLLO_GRAPH_REF` environment variables to use Uplink. It is recommended to use a contract variant of your graph, with a PQ list associated with that variant. That way, you control exactly what persisted queries are available to the MCP server. ```sh target/debug/apollo-mcp-server \ --directory \ -s graphql/weather/api.graphql \ --header "apollographql-client-name:my-web-app" \ --uplink ``` # Running Your Own Graph You can easily run the server with your own GraphQL schema and operations. For example with the stdio transport: ```json { "mcpServers": { "": { "command": "/target/debug/apollo-mcp-server", "args": [ "--directory", "", "--schema", "", "--operations", "", "--endpoint", "" ] } } } ``` The operation files are just `.graphql` files, with each file containing a single operation. Make sure to give your operations meaningful names, and document your schema as much as possible. Run your schema in Apollo Router at the endpoint given in your configuration file. Use MCP Inspector, or in Claude Desktop, click the hammer icon to see the description generated for your tools. # Introspection You can optionally enable support for allowing the AI model to introspect the schema and formulate its own queries. It is recommended that this only be done with a Contract variant schema, so you can control what parts of your schema are exposed to the model. To enable this mode, add `--introspect` to the MCP server command line. Two new tools will be exposed by the server: * `introspect` - returns information about GraphQL schema types * `execute` - executes an operation on the GraphQL endpoint The MCP client can then use these tools to provide schema information to the model, and allow the model to execute GraphQL operations based on that schema. # Running in a Container The MCP server is also available as a standalone docker container. The following command demonstrates how to use the container. Refer to previous sections for all valid server arguments. By default, the container expects all schema files to be present in the `/data` folder within the container, so make sure to mount your files there. The example below uses the provided weather example for reference ```sh docker run \ -it --rm \ --name apollo-mcp-server \ -p 5000:5000 \ -v $PWD/graphql/weather:/data \ ghcr.io/apollographql/apollo-mcp:latest \ --sse-port 5000 \ -s api.graphql \ # Other MCP server options... ``` # Licensing Source code in this repository is covered by the Elastic License 2.0. The default throughout the repository is a license under the Elastic License 2.0, unless a file header or a license file in a subdirectory specifies another license. [See the LICENSE](./LICENSE) for the full license text.