Skip to content

Commit 378b0f0

Browse files
shorgishorgi
committed
update get started with local binary. copyedit homepage. add rover dev mcp options table.
1 parent 96a01d6 commit 378b0f0

File tree

4 files changed

+128
-46
lines changed

4 files changed

+128
-46
lines changed

‎docs/source/command-reference.mdx

+25-7
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: Command Reference
33
subtitle: ""
4-
description: Reference guide for running Apollo MCP Server. Includes options
4+
description: Reference guide of options for running Apollo MCP Server.
55
---
66

77
<ExperimentalFeature />
@@ -16,18 +16,36 @@ apollo-mcp-server [OPTIONS] --directory <DIRECTORY> --schema <SCHEMA>
1616

1717
| Option | Description |
1818
| :-------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
19-
| `-d, --directory <DIRECTORY>` | The working directory to use. |
20-
| `-s, --schema <SCHEMA>` | The path to the GraphQL API schema file. |
21-
| `-c, --custom-scalars-config <CUSTOM_SCALARS_CONFIG>` | The path to the GraphQL custom_scalars_config file. |
19+
| `-d, --directory <DIRECTORY>` | The working directory to use. **Required** |
20+
| `-s, --schema <SCHEMA>` | The path to the GraphQL API schema file. **Required** |
21+
| `-c, --custom-scalars-config <CUSTOM_SCALARS_CONFIG>` | The path to the GraphQL custom_scalars_config file. [Learn more](/apollo-mcp-server/guides/#custom-scalars). |
2222
| `-e, --endpoint <ENDPOINT>` | The GraphQL endpoint the server will invoke.<br />[default: `http://127.0.0.1:4000`] |
2323
| `--header <HEADERS>` | Headers to send to the endpoint. |
2424
| `--sse-port <SSE_PORT>` | Start the server using the SSE transport on the given port. |
25-
| `-i, --introspection` | Expose the schema to the MCP client through `schema` and `execute` tools. |
26-
| `-u, --uplink` | Enable use of uplink to get the schema and persisted queries (requires `APOLLO_KEY` and `APOLLO_GRAPH_REF`). |
25+
| `-i, --introspection` | Expose the schema to the MCP client through `schema` and `execute` tools. [Learn more](/apollo-mcp-server/guides/#from-schema-introspection). |
26+
| `-u, --uplink` | Enable use of uplink to get the schema and persisted queries (requires `APOLLO_KEY` and `APOLLO_GRAPH_REF`). [Learn more](/apollo-mcp-server/guides/#from-graphos-managed-persisted-queries). |
2727
| `-x, --explorer` | Expose a tool to open queries in Apollo Explorer (requires `APOLLO_KEY` and `APOLLO_GRAPH_REF`). |
28-
| `-o, --operations [<OPERATIONS>...]` | Operation files to expose as MCP tools. |
28+
| `-o, --operations [<OPERATIONS>...]` | Operation files to expose as MCP tools. [Learn more](/apollo-mcp-server/guides/#from-operation-schema-files). |
2929
| `--manifest <MANIFEST>` | The path to the persisted query manifest containing operations. |
3030
| `-m, --allow-mutations <ALLOW_MUTATIONS>` | [default: `none`]<br /><br />Possible values:<ul><li>`none`: Don't allow any mutations</li><li>`explicit`: Allow explicit mutations, but don't allow the LLM to build them</li><li>`all`: Allow the LLM to build mutations</li></ul> |
3131
| `-h, --help` | Print help (see a summary with `-h`). |
3232

33+
### Mapping rover dev options
34+
35+
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.
36+
37+
Running `rover dev --mcp` starts an MCP server. Additional options, `--mcp*`, directly configure the MCP server.
38+
39+
The mapping of `rover dev` options to MCP server options:
40+
41+
| `rover dev` option | Equivalent MCP Server option |
42+
| :-------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
43+
| `--mcp-port <PORT>` | `--sse-port <PORT>` |
44+
| `--mcp-introspection` | `-i, --introspection` |
45+
| `--mcp-explorer` | `-x, --explorer` |
46+
| `--mcp-uplink` | `-u, --uplink` |
47+
| `--mcp-operations [<OPERATIONS>...]` | `-o, --operations [<OPERATIONS>...]` |
48+
| `--mcp-header <HEADERS>` | `--header <HEADERS>` |
49+
| `--mcp-manifest <MANIFEST>` | `--manifest <MANIFEST>` |
50+
3351

‎docs/source/get-started/index.mdx

+91-24
Original file line numberDiff line numberDiff line change
@@ -7,55 +7,93 @@ subtitle: Run Apollo MCP Server
77

88
Let's run Apollo MCP Server for the first time. You will:
99
- Understand an MCP server example.
10-
- Run an MCP server locally, using the example and Apollo Rover CLI.
11-
- Connect an MCP client and inspect and/or run the tools.
10+
- Run an MCP server for the example.
11+
- Connect MCP Inspector and inspect the tools.
12+
- Connect an MCP client and run the tools.
1213

1314
## Prerequisites
1415

15-
- Install [Apollo Rover CLI](/rover/getting-started) v0.30 or later.
1616
- Clone the [Apollo MCP Server repo](https://github.com/apollographql/apollo-mcp-server).
1717

1818
## Understand MCP server example
1919

20-
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. It also has files for configuring MCP tools from reading persisted queries registered with the graph.
20+
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.
2121

22-
Let's walk through the example files, located in the repo in `graphql/TheSpaceDevs`:
22+
Let's walk through the example files. They're located in the repo in `graphql/TheSpaceDevs/`:
2323
- `supergraph.yaml` is a [supergraph configuration file](/rover/commands/supergraphs#yaml-configuration-file) for the Rover CLI.
2424
- 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.
25-
- The `persisted_queries/` directory has a persisted queries manifest (PQM) file. It defines the operations that've been registered with the graph and that can be read by the MCP server to create corresponding tools.
25+
- 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.
2626

2727
## Run MCP server example
2828

29-
You can run the Apollo MCP Server together with a graph in a local development environment with a single `rover dev` command.
29+
Choose one of the options for running an MCP example:
3030

31+
- Running `rover dev` to start an MCP server using the SSE transport
32+
- Running a local binary of the MCP server using the stdio transport
33+
34+
Both use [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) to connect to and inspect the running server.
35+
<br/>
36+
37+
<Tabs>
38+
39+
<Tab label="rover dev + SSE">
40+
41+
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 SSE transport.
42+
43+
1. Install [Apollo Rover CLI](/rover/getting-started) v0.31 or later.
3144
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.
3245

3346
```sh showLineNumbers=false
3447
rover dev --supergraph-config ./graphql/TheSpaceDevs/supergraph.yaml \
35-
--mcp --mcp-port 5555 \
48+
--mcp --mcp-port 5000 \
3649
--mcp-operations ./graphql/TheSpaceDevs/operations/ExploreCelestialBodies.graphql ./graphql/TheSpaceDevs/operations/GetAstronautDetails.graphql ./graphql/TheSpaceDevs/operations/GetAstronautsCurrentlyInSpace.graphql ./graphql/TheSpaceDevs/operations/SearchUpcomingLaunches.graphql
3750
```
3851

3952
- `--mcp` starts an Apollo MCP server
4053
- `--mcp-port` sets the port of the server's SSE transport
4154
- `--mcp-operations` sets the list of operations
4255

43-
## Inspect MCP server
44-
45-
The [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) is a tool for testing and debugging MCP servers. Let's use it to validate our running server.
46-
47-
1. Install `npm`, if unavailable.
48-
1. Run the Inspector from a new terminal, then go to its returned URL (for example, [`http://127.0.0.1:6274`](http://127.0.0.1:6274)).
56+
1. Start MCP Inspector, then open a browser and go to [`http://127.0.0.1:6274`](http://127.0.0.1:6274):
4957

50-
```bash showLineNumbers=false
58+
```sh
5159
npx @modelcontextprotocol/inspector
5260
```
5361

54-
1. Fill in the details:
62+
1. Fill in the details in Inspector:
5563
- **Transport Type**: Select `SSE`
5664
- **URL**: Enter `http://localhost:5000/sse` (its port must match the `--mcp-port` of the server)
5765

58-
1. Click **Connect**, then click **List Tool**. Your operations should now be listed.
66+
1. Click **Connect**, then click **List Tool**. Inspector should show the tools from your server.
67+
68+
<img
69+
src="../images/mcp-getstarted-inspector.jpg"
70+
alt="MCP Inspector connected to running Apollo MCP Server"
71+
class="screenshot"
72+
width="600"
73+
/>
74+
75+
</Tab>
76+
77+
<Tab label="Local binary + stdio">
78+
79+
You can run an Apollo MCP Server locally to communicate over stdio.
80+
81+
1. Download the binary of the latest version of Apollo MCP Server. Add it to your path.
82+
1. Use MCP Inspector to run the Apollo MCP Server binary:
83+
84+
```sh showLineNumbers=false
85+
npx @modelcontextprotocol/inspector apollo-mcp-server \
86+
--directory <absolute-path-to-MCP-example-dir>
87+
--schema api.graphql \
88+
--operations operations/ExploreCelestialBodies.graphql operations/GetAstronautDetails.graphql operations/GetAstronautsCurrentlyInSpace.graphql operations/SearchUpcomingLaunches.graphql \
89+
--endpoint https://thespacedevs-production.up.railway.app/
90+
```
91+
1. Open a browser and go to the Inspector URL at [`http://127.0.0.1:6274`](http://127.0.0.1:6274).
92+
1. Fill in the details in Inspector:
93+
- **Transport Type**: Select `STDIO`
94+
- **Command**: Should be prepopulated with the command to run the MCP server
95+
96+
1. Click **Connect**, then click **List Tool**. Inspector should show the tools from your server.
5997

6098
<img
6199
src="../images/mcp-getstarted-inspector.jpg"
@@ -64,18 +102,43 @@ The [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) is a t
64102
width="600"
65103
/>
66104

105+
</Tab>
106+
</Tabs>
67107

68108
## Connect an MCP client
69109

70-
Connect an MCP client to your server and run its tools.
110+
### Claude for Desktop
71111

72-
<Tabs>
112+
You can configure Claude Desktop to use the tools from your MCP server.
113+
114+
1. Open Claude's JSON config file, and add a configuration to connect to the MCP server. You can connect via stdio or SSE transport:
73115

74-
<Tab label="Claude for Desktop">
116+
<CodeColumns cols={2}>
75117

76-
1. Open Claude's JSON config file, and add a configuration to connect to the MCP server via SSE transport:
118+
```json title="stdio"
119+
{
120+
"mcpServers": {
121+
"thespacedevs": {
122+
"command": "<absolute-path-to-MCP-server-binary>",
123+
"args": [
124+
"--directory",
125+
"<absolute-path-to-MCP-example-directory>",
126+
"--schema",
127+
"api.graphql",
128+
"--operations",
129+
"operations/ExploreCelestialBodies.graphql",
130+
"operations/GetAstronautDetails.graphql",
131+
"operations/GetAstronautsCurrentlyInSpace.graphql",
132+
"operations/SearchUpcomingLaunches.graphql",
133+
"--endpoint",
134+
"https://thespacedevs-production.up.railway.app/"
135+
]
136+
}
137+
}
138+
}
139+
```
77140

78-
```json
141+
```json title="SSE"
79142
{
80143
"mcpServers": {
81144
"thespacedevs": {
@@ -90,9 +153,13 @@ Connect an MCP client to your server and run its tools.
90153
}
91154
}
92155
```
156+
157+
</CodeColumns>
158+
93159
1. Restart Claude, then check that your server's tools are available from the input box.
94160
1. Ask a question that exercises the tools.
95161

96-
</Tab>
97162

98-
</Tabs>
163+
## Next steps
164+
165+
- Try creating tools from operations in persisted queries, via [persisted query manifests](/apollo-mcp-server/guides/#from-persisted-query-manifests) or [GraphOS](/apollo-mcp-server/guides/#from-graphos-managed-persisted-queries).

‎docs/source/guides/index.mdx

+5-8
Original file line numberDiff line numberDiff line change
@@ -128,26 +128,24 @@ If you register a persisted query with a specific client name instead of `null`,
128128
Use the `--header` 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.
129129

130130

131-
### From introspection
131+
### From schema introspection
132132

133-
You can optionally enable support for allowing an AI model to introspect the schema and formulate its own queries.
133+
For use cases where not all operations can be pre-defined, Apollo MCP Server supports tool creation based on graph introspection. This allows AI agents to explore a graph and execute operations dynamically.
134134

135-
To enable this introspection mode, run the MCP server with the `--introspect` option.
136-
137-
Two new tools will be exposed by the server:
135+
To enable these schema aware tools, run the MCP server with the `--introspection` option, which exposes two new tools:
138136

139137
* `schema` - returns the GraphQL schema
140138
* `execute` - executes an operation on the GraphQL endpoint
141139

142-
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.
140+
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.
143141

144142
<Tip>
145143

146144
Use a [contract variant](/graphos/platform/schema-management/delivery/contracts/overview) so you can control the parts of your graph that AI can introspect. [Learn more](/apollo-mcp-server/best-practices#use-contract-variants-to-control-ai-access-to-graphs)
147145

148146
</Tip>
149147

150-
### Adding context to tools
148+
### Documenting tools
151149

152150
TODO
153151

@@ -200,7 +198,6 @@ Starting MCP inspector...
200198

201199
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.
202200

203-
204201
### Debug over SSE transport
205202

206203
When running the MCP server over SSE transport, you can run MCP Inspector with the SSE transport.

0 commit comments

Comments
 (0)