Apollo MCP Server

--- title: Apollo MCP Server Quickstart subtitle: Create and run an MCP server in minutes with Apollo --- Apollo MCP Server is a [Model Context Protocol](https://modelcontextprotocol.io/) server that exposes your GraphQL API operations as MCP tools. This guide walks you through the process of creating, running and configuring an MCP server with Apollo. ## Prerequisites - [Rover CLI](/rover/getting-started) v0.36 or later. We'll use Rover to initialize a project and run the MCP server. Follow the instructions for [installing](/rover/getting-started) and [authenticating](/rover/getting-started#connecting-to-graphos) Rover with a GraphOS account. - [Node.js](https://nodejs.org/) v18 or later (for `mcp-remote`) - [Claude Desktop](https://claude.ai/download) or another MCP-compatible client ## Step 1: Create an MCP server Run the interactive initialization command: ```bash showLineNumbers=false rover init --mcp ``` The CLI wizard guides you through several prompts. Select **Create MCP tools from a new Apollo GraphOS project** and **Apollo graph with Connectors (connect to REST services)** as your starting point. You'll also need to select your organization and give your project a name and ID. The wizard shows all files that will be created, including: - MCP server configuration files - GraphQL schema and operations - Docker setup for (optional) deployment Type `Y` to confirm and create your project files. ## Step 2: Run your MCP Server You can start your MCP server locally with `rover dev`. 1. Choose the environment-specific command to load environment variables from the provided `.env` file and start the MCP server. <Tabs> <Tab label="Linux / MacOS"> ```terminal showLineNumbers=false set -a && source .env && set +a && rover dev --supergraph-config supergraph.yaml --mcp .apollo/mcp.local.yaml ``` </Tab> <Tab label="Windows Powershell"> ```terminal showLineNumbers=false Get-Content .env | ForEach-Object { $name, $value = $_.split('=',2); [System.Environment]::SetEnvironmentVariable($name, $value) } rover dev --supergraph-config supergraph.yaml --mcp .apollo/mcp.local.yaml ``` </Tab> </Tabs> 1. You should see some output indicating that the GraphQL server is running at `http://localhost:4000` and the MCP server is running at `http://127.0.0.1:8000`. 1. In a new terminal window, run the MCP Inspector to verify the server is running: ```terminal showLineNumbers=false npx @modelcontextprotocol/inspector http://127.0.0.1:8000/mcp --transport http ``` 1. This will automatically open your browser to `http://127.0.0.1:6274`. 1. Click **Connect**, then **List Tools** to see the available tools. ## Step 3: Connect to an MCP client Apollo MCP Server works with any MCP-compatible client. Choose your favorite client and follow the instructions to connect. <ExpansionPanel title="Claude Desktop (recommended)"> Open the `claude_desktop_config.json` file in one of the following paths: - Mac OS: `~/Library/Application\ Support/Claude/claude_desktop_config.json` - Windows: `%APPDATA%\Claude\claude_desktop_config.json` - Linux: `~/.config/Claude/claude_desktop_config.json` Copy the configuration: ```json { "mcpServers": { "mcp-My API": { "command": "npx", "args": [ "mcp-remote", "http://127.0.0.1:8000/mcp" ] } } } ``` </ExpansionPanel> <ExpansionPanel title="Claude Code"> Install using the CLI: ```bash claude mcp add apollo-mcp npx mcp-remote http://127.0.0.1:8000/mcp ``` </ExpansionPanel> <ExpansionPanel title="Cursor"> Click the button to quick install: <a href="cursor://anysphere.cursor-deeplink/mcp/install?name=apollo-mcp&config=eyJjb21tYW5kIjoibnB4IG1jcC1yZW1vdGUgaHR0cDovLzEyNy4wLjAuMTo4MDAwL21jcCJ9" hideExternalIcon> <img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Install Apollo MCP Server to Cursor" width="150px" noZoom/> </a> Or install manually: 1. Go to **Cursor Settings** → **MCP** → **Add new MCP Server** 2. Name: `Apollo MCP` (choose a title) 3. Command: `npx` 4. Arguments: `["mcp-remote", "http://127.0.0.1:8000/mcp"]` </ExpansionPanel> <ExpansionPanel title="Goose"> Add Apollo MCP Server to your Goose configuration. Edit your `~/.config/goose/profiles.yaml`: ```yaml default: provider: openai processor: gpt-4 accelerator: gpt-4o-mini moderator: passive toolkits: - name: developer - name: mcp requires: apollo-mcp: command: npx args: - mcp-remote - http://127.0.0.1:8000/mcp ``` Or use the Goose CLI to add the MCP server: ```bash goose mcp add apollo-mcp npx mcp-remote http://127.0.0.1:8000/mcp ``` </ExpansionPanel> <ExpansionPanel title="Cline (VS Code Extension)"> 1. Go to **Advanced settings** → **Extensions** → **Add custom extension** 2. Name: `Apollo MCP` 3. Type: **STDIO** 4. Command: `npx mcp-remote http://127.0.0.1:8000/mcp` </ExpansionPanel> <ExpansionPanel title="OpenCode"> Edit `~/.config/opencode/opencode.json`: ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "apollo-mcp": { "type": "local", "command": [ "npx", "mcp-remote", "http://127.0.0.1:8000/mcp" ], "enabled": true } } } ``` </ExpansionPanel> <ExpansionPanel title="Windsurf"> 1. Go to **Windsurf Settings → MCP → Add new MCP Server** 2. Name: `Apollo MCP` 3. Command: `npx` 4. Arguments: `["mcp-remote", "http://127.0.0.1:8000/mcp"]` Alternatively, edit your Windsurf configuration file directly: ```json { "mcpServers": { "apollo-mcp": { "command": "npx", "args": [ "mcp-remote", "http://127.0.0.1:8000/mcp" ] } } } ``` </ExpansionPanel> 1. Restart your MCP client. 1. Test the connection by asking: "What MCP tools do you have available?". 1. Verify GraphQL operations are listed as available tools. 1. Test a query using one of your configured operations. ## Step 4: Define MCP tools MCP tools are defined as GraphQL operations. The project template currently uses operation collections as the source of its tools. <Note> See [Define MCP Tools](/apollo-mcp-server/define-tools) for other ways to define MCP tools. </Note> 1. Navigate to Sandbox at [http://localhost:4000](http://localhost:4000). 1. Click the Bookmark icon to open Operation Collections. 1. Click **Sandbox** beside "Showing saved operations for your Sandbox, across all endpoints" and select your graph. This represents the graph name and ID you used when creating your project. 1. You'll see an operation collection called "Default MCP Tools". 1. Create a new operation in the middle panel: ```graphql # Retrieves product information query GetProducts { products { id name description } } ``` 1. Click the **Save** button and give it the name `GetProducts`. 1. Select the `Default MCP Tools` collection and click **Save**. 1. Restart your MCP client and test the connection by asking: "What MCP tools do you have available?". You should see the `GetProducts` tool listed. You can also test this with MCP Inspector. ## Step 5: Deploy your MCP server Apollo MCP Server can run in any container environment. ### Using the Apollo Runtime Container Your project includes a pre-configured `mcp.Dockerfile` for easy deployment. This container includes: - Apollo Router for serving your GraphQL API - Apollo MCP Server for MCP protocol support - All necessary dependencies 1. Build the container: ```bash docker build -f mcp.Dockerfile -t my-mcp-server . ``` 1. Run locally: ```bash docker run -p 4000:4000 -p 8000:8000 \ -e APOLLO_KEY=$APOLLO_KEY \ -e APOLLO_GRAPH_REF=$APOLLO_GRAPH_REF \ -e MCP_ENABLE=1 \ my-mcp-server ``` 1. Deploy to your platform. The container can be deployed to any platform supporting Docker, such as: AWS ECS/Fargate, Google Cloud Run, Azure Container Instances, Kubernetes, Fly.io, Railway, Render. 1. Ensure these variables are set in your deployment environment: | Variable | Description | Required | | ---------------------------- | ------------------------------- | -------- | | `APOLLO_KEY` | Your graph's API key | Yes | | `APOLLO_GRAPH_REF` | Your graph reference | Yes | | `APOLLO_MCP_TRANSPORT__PORT` | MCP server port (default: 8000) | No | | `APOLLO_ROUTER_PORT` | Router port (default: 4000) | No | For more deployment options, see the [Deploy the MCP Server](/apollo-mcp-server/deploy) page. ### Update client configuration After deploying, update your MCP client configuration to use the deployed URL: ```json { "mcpServers": { "my-api": { "command": "npx", "args": [ "mcp-remote", "https://your-deployed-server.com/mcp" ] } } } ``` ## Troubleshooting **Client doesn't see tools:** - Ensure you restarted your MCP client after configuration - Verify the Apollo MCP Server is running (`rover dev` command) - Check port numbers match between server and client config **Connection refused errors:** - Confirm the server is running on the correct port - Verify firewall settings allow connections to localhost:8000 - For remote connections, ensure the host is set to `0.0.0.0` in your config **Authentication issues:** - Verify environment variables are properly set - Check that your GraphQL endpoint accepts the provided headers - When using `rover dev` you can test your GraphQL endpoint using Sandbox at [http://localhost:4000](http://localhost:4000) ## Additional resources - [Tutorial: Getting started with MCP and GraphQL](https://www.apollographql.com/tutorials/intro-mcp-graphql) - [Tutorial: Agentic GraphQL: MCP for the Enterprise](https://www.apollographql.com/tutorials/enterprise-mcp-graphql) - [Blog: Getting Started with Apollo MCP Server](https://www.apollographql.com/blog/getting-started-with-apollo-mcp-server-for-any-graphql-api) ### Getting help If you're still having issues: - Check [Apollo MCP Server GitHub issues](https://github.com/apollographql/apollo-mcp-server/issues) - Join the [Apollo community forums](https://community.apollographql.com/c/mcp-server/41) - Contact your Apollo representative for direct support