Skip to content

Commit 8078f0e

Browse files
DaleSeoDaleSeo
committed
docs: add docs on the health check support
1 parent 43512a5 commit 8078f0e

File tree

2 files changed

+77
-22
lines changed

2 files changed

+77
-22
lines changed

‎docs/source/command-reference.mdx‎

Lines changed: 24 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -110,14 +110,14 @@ All fields are optional and have sensible default values.
110110
| `endpoint` | `URL` | `http://localhost:4000/` | The target GraphQL endpoint |
111111
| `graphos` | `GraphOS` | | Apollo-specific credential overrides |
112112
| `headers` | `Map<string, string>` | `{}` | List of hard-coded headers to include in all GraphQL requests |
113+
| `health_check` | `HealthCheck` | | Health check configuration |
113114
| `introspection` | `Introspection` | | Introspection configuration |
114115
| `logging` | `Logging` | | Logging configuration |
115116
| `operations` | `OperationSource` | | Operations configuration |
116117
| `overrides` | `Overrides` | | Overrides for server behavior |
117118
| `schema` | `SchemaSource` | | Schema configuration |
118119
| `transport` | `Transport` | | The type of server transport to use |
119120

120-
121121
#### GraphOS configuration
122122

123123
These fields are under the top-level `graphos` key.
@@ -129,6 +129,25 @@ These fields are under the top-level `graphos` key.
129129
| `apollo_registry_url` | `URL` | | The URL to use for Apollo's registry |
130130
| `apollo_uplink_endpoints` | `URL` | | List of uplink URL overrides. You can also provide this with the `APOLLO_UPLINK_ENDPOINTS` environment variable |
131131

132+
#### Health check configuration
133+
134+
These fields are under the top-level `health_check` key.
135+
136+
| Option | Type | Default | Description |
137+
| :---------------------------- | :--------- | :---------- | :--------------------------------------------------------------------------------- |
138+
| `enabled` | `bool` | `false` | Enable health check endpoints |
139+
| `path` | `string` | `"/health"` | Custom health check endpoint path |
140+
| `readiness` | `object` | | Readiness check configuration |
141+
| `readiness.allowed` | `number` | `100` | Maximum number of rejections allowed in a sampling interval before marking unready |
142+
| `readiness.interval` | `object` | | Readiness check interval configuration |
143+
| `readiness.interval.sampling` | `duration` | `"5s"` | How often to check the rejection count |
144+
| `readiness.interval.unready` | `duration` | `"10s"` | How long to wait before recovering from unready state (default: 2 \* sampling) |
145+
146+
<Note>
147+
148+
Health checks are only available when using the `streamable_http` transport. The health check feature is inspired by Apollo Router's health check implementation.
149+
150+
</Note>
132151

133152
#### Introspection configuration
134153

@@ -145,7 +164,6 @@ These fields are under the top-level `introspection` key.
145164
| `validate` | `object` | | Validation tool configuration |
146165
| `validate.enabled` | `bool` | `false` | Enable validation tool |
147166

148-
149167
#### Logging configuration
150168

151169
These fields are under the top-level `logging` key.
@@ -154,7 +172,6 @@ These fields are under the top-level `logging` key.
154172
| :------ | :-------------------------------------------------- | :------- | :------------------------------ |
155173
| `level` | `oneOf ["trace", "debug", "info", "warn", "error"]` | `"info"` | The minimum log level to record |
156174

157-
158175
#### Operation source configuration
159176

160177
These fields are under the top-level `operations` key. The available fields depend on the value of the nested `source` key.
@@ -170,8 +187,7 @@ The default value for `source` is `"infer"`.
170187
| Manifest | `source` | `"manifest"` | | Load operations from a persisted queries manifest file |
171188
| Manifest | `path` | `FilePath` | | The path to the persisted query manifest |
172189
| Uplink | `source` | `"uplink"` | | Load operations from an uplink manifest. Note: This source requires an Apollo key and graph reference |
173-
| Infer | `source` | `"infer"` | * | Infer where to load operations based on other configuration options. |
174-
190+
| Infer | `source` | `"infer"` | \* | Infer where to load operations based on other configuration options. |
175191

176192
#### Overrides configuration
177193

@@ -184,7 +200,6 @@ These fields are under the top-level `overrides` key.
184200
| `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 |
185201
| `mutation_mode` | `oneOf ["none", "explicit", "all"]` | `"none"` | Defines the mutation access level for the MCP server |
186202

187-
188203
#### Schema source configuration
189204

190205
These fields are under the top-level `schema` key. The available fields depend on the value of the nested `source` key.
@@ -194,8 +209,7 @@ The default value for `source` is `"uplink"`.
194209
| :----- | :------- | :--------- | :------ | :---------------------------------------------------------------------------------- |
195210
| Local | `source` | `"local"` | | Load schema from local file |
196211
| Local | `path` | `FilePath` | | Path to the GraphQL schema |
197-
| Uplink | `source` | `"uplink"` | * | Fetch the schema from uplink. Note: This requires an Apollo key and graph reference |
198-
212+
| Uplink | `source` | `"uplink"` | \* | Fetch the schema from uplink. Note: This requires an Apollo key and graph reference |
199213

200214
#### Transport configuration
201215

@@ -204,17 +218,16 @@ The default value for `type` is `"stdio"`.
204218

205219
| Type | Option | Type | Default | Description |
206220
| :------------- | :-------- | :------------------ | :---------- | :---------------------------------------------------------------------------------------------------------------------------- |
207-
| stdio | `type` | `"stdio"` | * | Use standard IO for communication between the server and client |
221+
| stdio | `type` | `"stdio"` | \* | Use standard IO for communication between the server and client |
208222
| SSE | `type` | `"sse"` | | Host the MCP server on the supplied configuration, using SSE for communication. Note: Deprecated in favor of `StreamableHTTP` |
209223
| SSE | `address` | `IpAddr` | `127.0.0.1` | The IP address to bind to |
210224
| SSE | `port` | `u16` | `5000` | The port to bind to |
211225
| StreamableHTTP | `type` | `"streamable_http"` | | Host the MCP server on the configuration, using streamable HTTP messages. |
212226
| StreamableHTTP | `address` | `IpAddr` | `127.0.0.1` | The IP address to bind to |
213227
| StreamableHTTP | `port` | `u16` | `5000` | The port to bind to |
214228

215-
216229
### Mapping rover dev options
217230

218231
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.
219232

220-
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>`.
233+
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>`.

‎docs/source/guides/index.mdx‎

Lines changed: 53 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -104,7 +104,7 @@ From the root of a local MCP Server repo, run the `apollo-mcp-server` binary wit
104104

105105
```yaml title="Example config for using Persisted Query Manifest"
106106
headers:
107-
'apollographql-client-name': 'my-web-app'
107+
"apollographql-client-name": "my-web-app"
108108
operations:
109109
source: manifest
110110
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/
135135

136136
```yaml title="Example config using GraphOS-managed persisted queries"
137137
headers:
138-
'apollographql-client-name': 'my-web-app'
138+
"apollographql-client-name": "my-web-app"
139139
operations:
140140
source: uplink
141141
schema:
@@ -186,12 +186,6 @@ introspection:
186186
apollo-mcp-server <path to the preceding config>
187187
```
188188

189-
{/*
190-
### Documenting tools
191-
192-
TODO
193-
\*/}
194-
195189
## Deploying the MCP server
196190

197191
There are two ways to deploy and operate the MCP server.
@@ -214,7 +208,7 @@ endpoint: https://thespacedevs-production.up.railway.app/
214208
operations:
215209
source: local
216210
paths:
217-
- /data/operations/
211+
- /data/operations/
218212
schema:
219213
source: local
220214
path: /data/api.graphql
@@ -263,7 +257,7 @@ You can inspect a local Apollo MCP Server by running it with MCP Inspector.
263257
operations:
264258
source: local
265259
paths:
266-
- <absolute path to this git repo>/graphql/weather/operations/
260+
- <absolute path to this git repo>/graphql/weather/operations/
267261
schema:
268262
source: local
269263
path: <absolute path to this git repo>/graphql/weather/api.graphql
@@ -304,7 +298,7 @@ You can also deploy the server as a container using the instructions in [Deployi
304298
operations:
305299
source: local
306300
paths:
307-
- <absolute path to this git repo>/graphql/weather/operations/
301+
- <absolute path to this git repo>/graphql/weather/operations/
308302
schema:
309303
source: local
310304
path: <absolute path to this git repo>/graphql/weather/api.graphql
@@ -331,6 +325,54 @@ npx @modelcontextprotocol/inspector
331325

332326
1. Click **Connect** and **List Tools**. You should see the tools for the operations you provided.
333327

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:
354+
355+
| Endpoint | Description | Response |
356+
| :------------------ | :----------------- | :--------------------------------------------------------------- |
357+
| `GET /health` | Basic health check | Always returns `{"status": "UP"}` |
358+
| `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+
### Readiness tracking
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+
334376
## Custom scalars configuration
335377

336378
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

Comments
 (0)