Skip to content

Improving the MCP quick start #84

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 10 commits into from
May 30, 2025
Merged

Improving the MCP quick start #84

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
22676df
Add what you'll build section in quickstart
kbychu May 23, 2025
76d5f39
Rewrite quickstart to simplify and add appropriate details
kbychu May 23, 2025
fd9521b
Fix port instruction
kbychu May 28, 2025
eed32a8
Don't use localhost
kbychu May 28, 2025
4e7c090
Merge branch 'main' into kchu-quickstart-docs-improvement
kbychu May 29, 2025
b9202ef
Merge branch 'main' into kchu-quickstart-docs-improvement
kbychu May 29, 2025
9d31e65
Update quickstart to be streamable http
kbychu May 29, 2025
0471876
Update to use streamable http instructions
kbychu May 29, 2025
9c06a79
Rover 0.32 required for Streamable HTTP
kbychu May 29, 2025
211dad3
Merge branch 'main' into kchu-quickstart-docs-improvement
kbychu May 30, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/source/command-reference.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -120,7 +120,7 @@ Specifying either the HTTP port or address (or both) will enable the Streamable

### Mapping rover dev options

You can use the [`rover dev`](/rover/commands/dev) command of Rover CLI v0.31 or later to run an Apollo MCP Server instance for local development.
You can use the [`rover dev`](/rover/commands/dev) command of Rover CLI v0.32 or later to run an Apollo MCP Server instance for local development.

Running `rover dev --mcp` starts an MCP Server. Additional options, `--mcp*`, directly configure the MCP Server.

Expand Down
255 changes: 153 additions & 102 deletions docs/source/quickstart.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,119 +11,199 @@ This feature is [experimental](/graphos/resources/feature-launch-stages#experime

Let's run Apollo MCP Server for the first time! You will:

- Understand an MCP Server example.
- Run an MCP Server example.
- Connect an MCP client (Claude Desktop) to the MCP Server.
- Understand an MCP Server example
- Run an MCP Server example
- Connect an MCP client (Claude Desktop) to the MCP Server

<OdysseyCallout>
## What You'll Build

If you learn best with videos and exercises, this [interactive course](https://www.apollographql.com/tutorials/intro-mcp-graphql) teaches you how to set up Apollo MCP Server and create tools from GraphQL operations.
In this quickstart, you'll create a working AI integration where Claude Desktop can query space-related data through GraphQL. By the end, you'll be able to:

</OdysseyCallout>
- Ask Claude natural questions like "Who are the astronauts currently in space?" or "What rocket launches are coming up?"
- See Claude use MCP tools to fetch real-time data from The Space Devs API
- Understand how GraphQL operations become AI-accessible tools

## Prerequisites
Here's what the end result looks like:

- Clone the [Apollo MCP Server repo](https://github.com/apollographql/apollo-mcp-server).
> **You**: "Tell me about the astronauts currently in space"
> **Claude**: *[Uses GetAstronautsCurrentlyInSpace tool]* "There are currently 7 astronauts aboard the International Space Station..."

## Step 1: Understand MCP Server example
This example uses a pre-built space API, but the same approach works with any GraphQL API - including your own production services.

This guide uses an MCP example from the Apollo MCP Server repo. The example uses APIs from [The Space Devs](https://thespacedevs.com/), and it defines a federated graph and the GraphQL operations of the graph to expose as MCP tools.
<OdysseyCallout>

Let's walk through the example files. They're located in the repo in `graphql/TheSpaceDevs/`:
- `supergraph.yaml` is a [supergraph configuration file](/rover/commands/supergraphs#yaml-configuration-file) for the Rover CLI.
- The `operations/` directory has `*.graphql`operations schema files. Each file defines a GraphQL operation on the graph, and Apollo MCP Server creates an MCP tool from each operation file it's given.
- The `persisted_queries/` directory has a persisted query manifest (PQM) file. It defines the operations that've been registered with the graph as persisted queries and that can be read and turned into tools by the MCP Server.
If you learn best with videos and exercises, this [interactive course](https://www.apollographql.com/tutorials/intro-mcp-graphql) teaches you how to set up Apollo MCP Server and create tools from GraphQL operations.

## Step 2: Run MCP Server example
</OdysseyCallout>

Choose one of the options for running an MCP example:
## Prerequisites

- Running `rover dev` to start an MCP Server using the Streamable HTTP transport
- Running a local binary of the MCP Server using the stdio transport
- Running a container of the MCP Server using the SSE transport
- Clone the [Apollo MCP Server repo](https://github.com/apollographql/apollo-mcp-server)
- Install [Apollo Rover CLI](/rover/getting-started) v0.32 or later

All use [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) to connect to and inspect the running server.
<br/>
## Step 1: Understand the Example

<Tabs>
This guide uses an MCP example from the Apollo MCP Server repo. The example uses APIs from [The Space Devs](https://thespacedevs.com/), and it defines a federated graph and the GraphQL operations of the graph to expose as MCP tools.

<Tab label="rover dev + Streamable HTTP">
The example files located in `graphql/TheSpaceDevs/` include:
- **A federated graph** connecting to The Space Devs API
- `supergraph.yaml` is a [supergraph configuration file](/rover/commands/supergraphs#yaml-configuration-file) used by the Rover CLI
- **4 pre-built operations** that become your AI tools:
- `ExploreCelestialBodies` - Search planets, moons, and stars
- `GetAstronautDetails` - Get info about specific astronauts
- `GetAstronautsCurrentlyInSpace` - See who's in space right now
- `SearchUpcomingLaunches` - Find upcoming rocket launches

You can run the Apollo MCP Server together with a graph in a local development environment with a single `rover dev` command. Rover starts an MCP Server that communicates via the Streamable HTTP transport.
## Step 2: Run the MCP Server

1. Install [Apollo Rover CLI](/rover/getting-started) v0.31 or later.
1. From the root directory of your local repo, run `rover dev` to start a local graph, using `--mcp*` options to start and configure an Apollo MCP Server.
1. From the root directory of your local repo, run `rover dev` to start a local graph with an MCP Server:

```sh showLineNumbers=false
rover dev --supergraph-config ./graphql/TheSpaceDevs/supergraph.yaml \
--mcp \
--mcp-operations ./graphql/TheSpaceDevs/operations/ExploreCelestialBodies.graphql ./graphql/TheSpaceDevs/operations/GetAstronautDetails.graphql ./graphql/TheSpaceDevs/operations/GetAstronautsCurrentlyInSpace.graphql ./graphql/TheSpaceDevs/operations/SearchUpcomingLaunches.graphql
rover dev --supergraph-config ./graphql/TheSpaceDevs/supergraph.yaml \
--mcp \
--mcp-operations ./graphql/TheSpaceDevs/operations/ExploreCelestialBodies.graphql ./graphql/TheSpaceDevs/operations/GetAstronautDetails.graphql ./graphql/TheSpaceDevs/operations/GetAstronautsCurrentlyInSpace.graphql ./graphql/TheSpaceDevs/operations/SearchUpcomingLaunches.graphql
```

- `--mcp` starts an Apollo MCP Server
- `--mcp-operations` sets the list of operations
This command:
- Starts a local graph using the supergraph configuration
- Starts an MCP Server with the `--mcp` flag
- Exposes the specified operations as MCP tools

1. Start MCP Inspector, then open a browser and go to [`http://127.0.0.1:6274`](http://127.0.0.1:6274):
2. Start MCP Inspector to verify the server is running:

```sh
npx @modelcontextprotocol/inspector
```

1. Fill in the details in Inspector:
- **Transport Type**: Select `Streamable HTTP`
- **URL**: Enter `http://localhost:5000/mcp` (5000 is the default port of the MCP server)
3. Open a browser and go to [`http://127.0.0.1:6274`](http://127.0.0.1:6274)

1. Click **Connect**, then click **List Tool**. Inspector should show the tools from your server.
4. In Inspector:
- Select `Streamable HTTP` as the Transport Type
- Enter `http://127.0.0.1:5000/mcp` as the URL
- Click **Connect**, then **List Tools**

<img
src="./images/mcp-getstarted-inspector-http.jpg"
alt="MCP Inspector connected to running Apollo MCP Server"
class="screenshot"
width="600"
/>
You should see the tools from your server listed.

</Tab>
## Step 3: Connect Claude Desktop

<Tab label="Local binary + stdio">
First, locate your Claude configuration file:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`

You can run an Apollo MCP Server locally to communicate over stdio.
Then add the following configuration

1. Download the binary of the latest version of Apollo MCP Server. Add it to your path.
1. Use MCP Inspector to run the Apollo MCP Server binary:
1. Open Claude's JSON config file and add this configuration:

```sh showLineNumbers=false
npx @modelcontextprotocol/inspector apollo-mcp-server \
--directory <absolute-path-to-MCP-example-dir>
--schema api.graphql \
--operations operations \
--endpoint https://thespacedevs-production.up.railway.app/
```json
{
"mcpServers": {
"thespacedevs": {
"command": "npx",
"args": [
"mcp-remote",
"http://127.0.0.1:5000/mcp",
]
}
}
}
```
1. Open a browser and go to the Inspector URL at [`http://127.0.0.1:6274`](http://127.0.0.1:6274).
1. Fill in the details in Inspector:
- **Transport Type**: Select `STDIO`
- **Command**: Should be prepopulated with the command to run the MCP Server

1. Click **Connect**, then click **List Tool**. Inspector should show the tools from your server.

<img
src="./images/mcp-getstarted-inspector-stdio.jpg"
alt="MCP Inspector connected to running Apollo MCP Server"
class="screenshot"
width="600"
/>
2. Restart Claude

## Step 4: Test Your Setup

Let's verify everything is working:

1. In Claude Desktop, type: "What MCP tools do you have available?"
- Claude should list tools like `ExploreCelestialBodies`, `GetAstronautDetails`, etc.

2. Try a real query: "Who are the astronauts currently in space?"
- Claude should use the `GetAstronautsCurrentlyInSpace` tool and return current data

3. If Claude can't see the tools:
- Ensure you restarted Claude Desktop after editing the config
- Check that your MCP server is still running
- Verify the port numbers match between your server and Claude config

## Troubleshooting

### Common Issues

#### MCP Server Won't Start
- **Error**: "Port 5000 is already in use"
- Solution: Kill any existing processes using port 5000 or specify a different port with `--mcp-sse-port` flag using Rover Dev or `--sse-port` when running the MCP server directly
- **Error**: "Failed to load supergraph configuration"
- Solution: Verify you're running the command from the repo root directory
- Solution: Check that the path to `supergraph.yaml` is correct

#### MCP Inspector Connection Issues
- **Error**: "Failed to connect to server"
- Solution: Ensure the MCP server is running (check terminal output)
- Solution: Verify you're using the correct URL (`http://127.0.0.1:5000/mcp`)
- Solution: Check if your firewall is blocking the connection

#### Claude Desktop Issues
- **Problem**: Claude doesn't recognize the tools
- Solution: Verify the config file path is correct for your OS
- Solution: Ensure the JSON is properly formatted (no trailing commas)
- Solution: Try restarting Claude Desktop completely
- **Problem**: "Connection refused" errors
- Solution: Check if the MCP server is still running
- Solution: Verify the port numbers match in both the server and Claude config

#### GraphQL Operation Issues
- **Error**: "Operation not found"
- Solution: Verify the operation files exist in the specified path
- Solution: Check that the operation names match exactly
- **Error**: "Schema validation failed"
- Solution: Ensure your GraphQL operations match the schema
- Solution: Check for syntax errors in your operation files

### Getting Help

If you're still having issues:
1. Check the [Apollo MCP Server GitHub issues](https://github.com/apollographql/apollo-mcp-server/issues)
2. Join the [Apollo Community MCP Server Category](https://community.apollographql.com/c/mcp-server/41)
3. Contact your Apollo representative for direct support

</Tab>
</Tabs>
## Next Steps

## Step 3: Connect an MCP client
See the [user guide](/apollo-mcp-server/guides) to learn how to create tools from:
- [Operation schema files](/apollo-mcp-server/guides#from-operation-schema-files)
- [Persisted query manifests](/apollo-mcp-server/guides/#from-persisted-query-manifests)
- [Schema introspection](/apollo-mcp-server/guides/#from-schema-introspection)

This quickstart using Claude Desktop as the MCP client. Configure Claude Desktop to use the tools from your MCP Server with these steps:
### Additional Resources

1. Open Claude's JSON config file, and add a configuration to connect to the MCP Server. You can connect via stdio or the Streamable HTTP transport:
Check out these blog posts to learn more about Apollo MCP Server:
- [Getting started with Apollo MCP Server](https://www.apollographql.com/blog/getting-started-with-apollo-mcp-server-for-any-graphql-api)
- [The Future of MCP is GraphQL](https://www.apollographql.com/blog/the-future-of-mcp-is-graphql)

### Advanced Options

<details>
<summary>Alternative ways to run the MCP Server</summary>

<CodeColumns cols={2}>
#### Using STDIO Transport

```json title="stdio"
You can run the MCP Server using STDIO transport instead of Streamable HTTP. This is useful for certain environments or when you need more direct control over the server process.

1. Download the binary of the latest version of Apollo MCP Server
2. Use MCP Inspector to run the server:

```sh
npx @modelcontextprotocol/inspector apollo-mcp-server \
--directory <absolute-path-to-MCP-example-dir> \
--schema api.graphql \
--operations operations \
--endpoint https://thespacedevs-production.up.railway.app/
```

3. Configure Claude Desktop to use STDIO:

```json
{
"mcpServers": {
"thespacedevs": {
Expand All @@ -142,34 +222,5 @@ This quickstart using Claude Desktop as the MCP client. Configure Claude Desktop
}
}
```

```json title="Streamable HTTP"
{
"mcpServers": {
"thespacedevs": {
"command": "npx",
"args": [
"mcp-remote",
"http://127.0.0.1:5000/mcp"
]
}
}
}
```

</CodeColumns>

1. Restart Claude, then check that your server's tools are available from the input box.

That's it! You've hooked up the Apollo MCP Server to Claude and can now use the MCP Server's tools in Claude.

## Next steps

See the [user guide](/apollo-mcp-server/guides) to learn how to create tools from [operation schema files](/apollo-mcp-server/guides#from-operation-schema-files), [persisted query manifests](/apollo-mcp-server/guides/#from-persisted-query-manifests), or [schema introspection](/apollo-mcp-server/guides/#from-schema-introspection).

### Additional resources

Check out these blog posts to learn more about Apollo MCP Server:

- [Getting started with Apollo MCP Server](https://www.apollographql.com/blog/getting-started-with-apollo-mcp-server-for-any-graphql-api)
- [The Future of MCP is GraphQL](https://www.apollographql.com/blog/the-future-of-mcp-is-graphql)

</details>