You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
| `transport` | `Transport` | | The type of server transport to use |
143
144
144
-
145
145
#### GraphOS configuration
146
146
147
147
These fields are under the top-level `graphos` key and define your GraphOS graph credentials and endpoints.
@@ -153,6 +153,25 @@ These fields are under the top-level `graphos` key and define your GraphOS graph
153
153
| `apollo_registry_url` | `URL` | | The URL to use for Apollo's registry |
154
154
| `apollo_uplink_endpoints` | `URL` | | List of uplink URL overrides. You can also provide this with the `APOLLO_UPLINK_ENDPOINTS` environment variable |
155
155
156
+
#### Health check configuration
157
+
158
+
These fields are under the top-level `health_check` key.
| `readiness.interval.sampling` | `duration` | `"5s"` | How often to check the rejection count |
168
+
| `readiness.interval.unready` | `duration` | `"10s"` | How long to wait before recovering from unready state (default: 2 \* sampling) |
169
+
170
+
<Note>
171
+
172
+
Health checks are only available when using the `streamable_http` transport. The health check feature is inspired by Apollo Router's health check implementation.
173
+
174
+
</Note>
156
175
157
176
#### Introspection configuration
158
177
@@ -166,7 +185,8 @@ These fields are under the top-level `introspection` key. Learn more about the M
| `level` | `oneOf ["trace", "debug", "info", "warn", "error"]` | `"info"` | The minimum log level to record |
178
198
179
-
180
199
#### Operation source configuration
181
200
182
201
These fields are under the top-level `operations` key. The available fields depend on the value of the nested `source` key.
@@ -192,8 +211,7 @@ The default value for `source` is `"infer"`.
192
211
| Manifest | `source` | `"manifest"` | | Load operations from a persisted queries manifest file |
193
212
| Manifest | `path` | `FilePath` | | The path to the persisted query manifest |
194
213
| Uplink | `source` | `"uplink"` | | Load operations from an uplink manifest. Note: This source requires an Apollo key and graph reference |
195
-
| Infer | `source` | `"infer"` | * | Infer where to load operations based on other configuration options. |
196
-
214
+
| Infer | `source` | `"infer"` | \* | Infer where to load operations based on other configuration options. |
197
215
198
216
#### Overrides configuration
199
217
@@ -206,7 +224,6 @@ These fields are under the top-level `overrides` key.
206
224
| `enable_explorer` | `bool` | `false` | Expose a tool that returns the URL to open a GraphQL operation in Apollo Explorer. Note: This requires a GraphOS graph reference |
207
225
| `mutation_mode` | `oneOf ["none", "explicit", "all"]` | `"none"` | Defines the mutation access level for the MCP server |
208
226
209
-
210
227
#### Schema source configuration
211
228
212
229
These fields are under the top-level `schema` key. The available fields depend on the value of the nested `source` key.
@@ -216,8 +233,7 @@ The default value for `source` is `"uplink"`.
| stdio | `type` | `"stdio"` | * | Use standard IO for communication between the server and client |
245
+
| stdio | `type` | `"stdio"` | \* | Use standard IO for communication between the server and client |
230
246
| SSE | `type` | `"sse"` | | Host the MCP server on the supplied configuration, using SSE for communication. Note: Deprecated in favor of `StreamableHTTP` |
231
247
| SSE | `address` | `IpAddr` | `127.0.0.1` | The IP address to bind to |
232
248
| SSE | `port` | `u16` | `5000` | The port to bind to |
233
249
| StreamableHTTP | `type` | `"streamable_http"` | | Host the MCP server on the configuration, using streamable HTTP messages. |
234
250
| StreamableHTTP | `address` | `IpAddr` | `127.0.0.1` | The IP address to bind to |
235
251
| StreamableHTTP | `port` | `u16` | `5000` | The port to bind to |
236
252
237
-
238
253
### Mapping rover dev options
239
254
240
255
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.
241
256
242
-
Running `rover dev --mcp` starts an MCP Server. An optional configuration file path can be provided to configure the MCP server via `rover dev --mcp <PATH/TO/CONFIG>`.
257
+
Running `rover dev --mcp` starts an MCP Server. An optional configuration file path can be provided to configure the MCP server via `rover dev --mcp <PATH/TO/CONFIG>`.
Copy file name to clipboardExpand all lines: docs/source/guides/index.mdx
+56-11Lines changed: 56 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -104,7 +104,7 @@ From the root of a local MCP Server repo, run the `apollo-mcp-server` binary wit
104
104
105
105
```yaml title="Example config for using Persisted Query Manifest"
106
106
headers:
107
-
'apollographql-client-name': 'my-web-app'
107
+
"apollographql-client-name": "my-web-app"
108
108
operations:
109
109
source: manifest
110
110
path: <absolute path to this local repo>/graphql/weather/persisted_queries/apollo.json
@@ -135,7 +135,7 @@ Use a [contract variant](/graphos/platform/schema-management/delivery/contracts/
135
135
136
136
```yaml title="Example config using GraphOS-managed persisted queries"
137
137
headers:
138
-
'apollographql-client-name': 'my-web-app'
138
+
"apollographql-client-name": "my-web-app"
139
139
operations:
140
140
source: uplink
141
141
schema:
@@ -161,6 +161,7 @@ You can enable the following introspection tools:
161
161
162
162
- `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.
163
163
- `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.
164
+
- `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.
164
165
- `execute`- executes an operation on the GraphQL endpoint
165
166
166
167
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.
@@ -177,18 +178,14 @@ introspection:
177
178
enabled: true
178
179
introspect:
179
180
enabled: true
181
+
validate:
182
+
enabled: true
180
183
```
181
184
182
185
```sh title="Example command using introspection"
183
186
apollo-mcp-server <path to the preceding config>
184
187
```
185
188
186
-
{/*
187
-
### Documenting tools
188
-
189
-
TODO
190
-
\*/}
191
-
192
189
## Deploying the MCP server
193
190
194
191
There are two ways to deploy and operate the MCP server.
1. Click **Connect** and **List Tools**. You should see the tools for the operations you provided.
330
327
328
+
## Health checks
329
+
330
+
Apollo MCP Server provides health check endpoints for monitoring server health and readiness. This feature is useful for load balancers, container orchestrators, and monitoring systems.
331
+
332
+
### Configuration
333
+
334
+
Health checks are only available when using the `streamable_http` transport and must be explicitly enabled:
335
+
336
+
```yaml title="Example health check configuration"
337
+
transport:
338
+
type: streamable_http
339
+
address: 127.0.0.1
340
+
port: 5000
341
+
health_check:
342
+
enabled: true
343
+
path: /health
344
+
readiness:
345
+
allowed: 50
346
+
interval:
347
+
sampling: 10s
348
+
unready: 30s
349
+
```
350
+
351
+
### Endpoints
352
+
353
+
The health check provides different responses based on query parameters:
| `GET /health?live` | Liveness check | Returns `{"status": "UP"}` if server is alive |
359
+
| `GET /health?ready` | Readiness check | Returns `{"status": "UP"}` if server is ready to handle requests |
360
+
361
+
### Probes
362
+
363
+
The server tracks failed requests and automatically marks itself as unready if too many failures occur within a sampling interval:
364
+
365
+
- **Sampling interval**: How often the server checks the rejection count (default: 5 seconds)
366
+
- **Allowed rejections**: Maximum failures allowed before becoming unready (default: 100)
367
+
- **Recovery time**: How long to wait before attempting to recover (default: 2x sampling interval)
368
+
369
+
When the server becomes unready:
370
+
371
+
- The `/health?ready` endpoint returns HTTP 503 with `{"status": "DOWN"}`
372
+
- After the recovery period, the rejection counter resets and the server becomes ready again
373
+
374
+
This allows external systems to automatically route traffic away from unhealthy servers and back when they recover.
375
+
331
376
## Custom scalars configuration
332
377
333
378
You can specify a custom scalars configuration JSON file to map a custom scalar to a [JSON schema type](https://json-schema.org/understanding-json-schema/reference/type). The JSON file is an object with custom scalar names as keys and JSON schema types as values:
0 commit comments