Skip to content

Simplify tables and add examples #373

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 3 commits into from
Nov 12, 2025
Merged

Simplify tables and add examples #373

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e0a5e4a
Simplify tables and add examples
jcaudle Sep 19, 2025
5451372
Fix indentation in example YAML
jcaudle Sep 24, 2025
d4f8b72
Address AI style review failure
jcaudle Nov 11, 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
90 changes: 50 additions & 40 deletions docs/source/config-file.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -165,17 +165,17 @@
These fields are under the top-level `operations` key. The available fields depend on the value of the nested `source` key.
The default value for `source` is `"infer"`. Learn more about [defining tools as operations](/apollo-mcp-server/define-tools).

| Source | Option | Type | Default | Description |
| :----------------- | :------- | :--------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------ |
| GraphOS Collection | `source` | `"collection"` | | Load operations from a GraphOS collection |
| GraphOS Collection | `id` | `string` | | The collection ID to use in GraphOS. Use `default` for the default collection. [Learn more](/apollo-mcp-server/define-tools#from-operation-collection). |
| Introspection | `source` | `"introspect"` | | Load operations by introspecting the schema. Note: You must enable introspection to use this source |
| Local | `source` | `"local"` | | Load operations from local GraphQL files or directories |
| Local | `paths` | `List<FilePath>` | | Paths to GraphQL files or directories to search. Note: These paths are relative to the location from which you are running Apollo MCP Server. |
| Manifest | `source` | `"manifest"` | | Load operations from a persisted queries manifest file |
| Manifest | `path` | `FilePath` | | The path to the persisted query manifest |
| Uplink | `source` | `"uplink"` | | Load operations from an uplink manifest. Note: This source requires an Apollo key and graph reference |
| Infer | `source` | `"infer"` | \* | Infer where to load operations based on other configuration options. |
| Source | Option | Type | Description |
| :----------------- | :------- | :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ |
| GraphOS Collection | `source` | `"collection"` | Load operations from a GraphOS collection |
| GraphOS Collection | `id` | `string` | The collection ID to use in GraphOS. Use `default` for the default collection. [Learn more](/apollo-mcp-server/define-tools#from-operation-collection). |

Check warning on line 171 in docs/source/config-file.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/config-file.mdx#L171 

Link text should be descriptive of the link's destination. 'Learn more' is too generic.

```suggestion
| GraphOS Collection | `id`     | `string`         | The collection ID to use in GraphOS. Use `default` for the default collection. [Learn more about operation collections](/apollo-mcp-server/define-tools#from-operation-collection). |
```
| Introspection | `source` | `"introspect"` | Load operations by introspecting the schema. Note: You must enable introspection to use this source |
| Local | `source` | `"local"` | Load operations from local GraphQL files or directories |
| Local | `paths` | `List<FilePath>` | Paths to GraphQL files or directories to search. Note: These paths are relative to the location from which you are running Apollo MCP Server. |

Check notice on line 174 in docs/source/config-file.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/config-file.mdx#L174 

Use simpler language for clarity. 'where you run' is more direct than 'from which you are running'.

```suggestion
| Local              | `paths`  | `List<FilePath>` | Paths to GraphQL files or directories to search. Note: These paths are relative to the directory where you run the Apollo MCP Server.           |
```
| Manifest | `source` | `"manifest"` | Load operations from a persisted queries manifest file |
| Manifest | `path` | `FilePath` | The path to the persisted query manifest |
| Uplink | `source` | `"uplink"` | Load operations from an uplink manifest. Note: This source requires an Apollo key and graph reference |
| Infer | `source` | `"infer"` | Infer where to load operations based on other configuration options. |

### Overrides

Expand All @@ -193,52 +193,50 @@
These fields are under the top-level `schema` key. The available fields depend on the value of the nested `source` key.
The default value for `source` is `"uplink"`.

| Source | Option | Type | Default | Description |
| :----- | :------- | :--------- | :------ | :---------------------------------------------------------------------------------- |
| Local | `source` | `"local"` | | Load schema from local file |
| Local | `path` | `FilePath` | | Path to the GraphQL schema |
| Uplink | `source` | `"uplink"` | \* | Fetch the schema from uplink. Note: This requires an Apollo key and graph reference |
| Source | Option | Type | Description |
| :----- | :------- | :--------- | :---------------------------------------------------------------------------------- |
| Local | `source` | `"local"` | Load schema from local file |
| Local | `path` | `FilePath` | Path to the GraphQL schema |
| Uplink | `source` | `"uplink"` | Fetch the schema from uplink. Note: This requires an Apollo key and graph reference |

### Transport

These fields are under the top-level `transport` key, to configure running the MCP Server in different environments - stdio, Streamable HTTP or SSE (deprecated).

```
```yaml
transport:
type: stdio
type: streamable_http
address: 127.0.0.1
port: 5000
stateful_mode: true
```

The available fields depend on the value of the nested `type` key:
##### Type

##### stdio (default)
The available fields depend on the value of the nested `type` key. The default type is `stdio`:

| Option | Value | Default Value | Description |
| :----- | :-------- | :------------ | :-------------------------------------------------------------- |
| `type` | `"stdio"` | \* | Use standard IO for communication between the server and client |
| Option | Description |
| :-------------------- | :--------------------------------------------------------------------------------------------------------------- |
| `"stdio"` | Use standard IO for communication between the server and client |
| `"streamable_http"` | Host the MCP server on the configuration, using streamable HTTP messages |
| `"sse"` | Host the MCP server on the supplied config, using SSE for communication. Deprecated in favor of `StreamableHTTP` |

Check warning on line 222 in docs/source/config-file.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/config-file.mdx#L222 

The value used in configuration is `streamable_http`, not `StreamableHTTP`. Use the correct symbol name for consistency.

```suggestion
| `"sse"`               | Host the MCP server on the supplied config, using SSE for communication. Deprecated in favor of `streamable_http` |
```

##### Streamable HTTP
##### Transport Type Specific options

Check warning on line 224 in docs/source/config-file.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/config-file.mdx#L224 

Headings must use sentence case.

```suggestion
##### Transport type-specific options
```

| Option | Value | Value Type | Description |
| :-------------- | :-------------------- | :--------- | :------------------------------------------------------------------------ |
| `type` | `"streamable_http"` | | Host the MCP server on the configuration, using streamable HTTP messages. |
| `address` | `127.0.0.1` (default) | `IpAddr` | The IP address to bind to |
| `port` | `8000` (default) | `u16` | The port to bind to |
| `stateful_mode` | `true` (default) | `bool` | Flag to enable or disable stateful mode and session management. |
Some transport types support further configuration. For both `streamable_http` and `sse`, you can set the `address` and `port`. For `streamable_http`, you can also set `stateful_mode`.

| Option | Type | Default | Description |
| :-------------- | :--------- | :---------- | :----------------------------------------------------------------------------------- |
| `address` | `IpAddr` | `127.0.0.1` | The IP address to bind to |
| `port` | `u16` | `8000` | The port to bind to |
| `stateful_mode` | `bool` | `true` | Flag to enable or disable stateful mode and session management. Not supported by SSE |

<Note>

For Apollo MCP Server `≤v1.0.0`, the default `port` value is `5000`. In `v1.1.0`, the default `port` option was changed to `8000` to avoid conflicts with common development tools and services that typically use port 5000 (such as macOS AirPlay, Flask development servers, and other local services).

</Note>

##### SSE (Deprecated, use StreamableHTTP)

| Option | Value | Value Type | Description |
| :-------- | :-------------------- | :--------- | :--------------------------------------------------------------------------------------------------------------- |
| `type` | `"sse"` | | Host the MCP server on the supplied config, using SSE for communication. Deprecated in favor of `StreamableHTTP` |
| `address` | `127.0.0.1` (default) | `IpAddr` | The IP address to bind to |
| `port` | `8000` (default) | `u16` | The port to bind to |

### Auth

These fields are under the top-level `transport` key, nested under the `auth` key. Learn more about [authorization and authentication](/apollo-mcp-server/auth).
Expand Down Expand Up @@ -339,11 +337,11 @@
| `always_off` | `string` | Sampling is turned off, no traces will be exported. |
| `0.0-1.0` | `f64` | Percentage of traces to export. |

## Example config file
## Example config files

Check warning on line 340 in docs/source/config-file.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/config-file.mdx#L340 

Headings must use sentence case. Use 'configuration' instead of the abbreviation 'config' for clarity.

```suggestion
## Example configuration files
```

The following example file sets your endpoint to `localhost:4001`, configures transport over Streamable HTTP, enables introspection, and provides two local MCP operations for the server to expose.

```yaml config.yaml
```yaml title="config.yaml"
endpoint: http://localhost:4001/
transport:
type: streamable_http
Expand All @@ -357,6 +355,18 @@
- relative/path/to/your/operations/listing.graphql
```

This configuration file will set up Streamable HTTP transport, enables introspection, and makes all operations derive from introspection:

Check warning on line 358 in docs/source/config-file.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/config-file.mdx#L358 

Use the present tense instead of the future tense. The list of verbs should also be parallel for better readability.

```suggestion
This configuration file sets up Streamable HTTP transport, enables introspection, and configures all operations to derive from introspection:
```

```yaml title="config.yaml"
transport:
type: streamable_http
introspection:
introspect:
enabled: true
operations:
source: introspect
```

## Override configuration options using environment variables

You can override configuration options using environment variables. The environment variable name is the same as the option name, but with `APOLLO_MCP_` prefixed. You can use `__` to mark nested options.
Expand Down