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

Open
wants to merge 3 commits into
base: develop
Choose a base branch
from
Open

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
1c0bd34
Simplify tables and add examples
jcaudle Sep 19, 2025
30e876e
Fix indentation in example YAML
jcaudle Sep 24, 2025
5aa22e9
Merge branch 'develop' into DXM-256
jcaudle Sep 26, 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: 52 additions & 38 deletions docs/source/config-file.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -113,17 +113,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). |
| 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. |

### Overrides

Expand All @@ -141,45 +141,46 @@
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 170 in docs/source/config-file.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/config-file.mdx#L170 

The name of the transport type should be consistent with its definition in the configuration.

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

##### Streamable HTTP
##### 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` | `5000` (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. Streamable HTTP and SSE both allow setting address and port. Streamable HTTP also supoorts setting stateful mode.

Check warning 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 

This change fixes a typo, improves clarity by using active voice, and correctly applies code formatting to configuration keys.

```suggestion
Some transport types support additional configuration. For both Streamable HTTP and SSE, you can set the <code>address</code> and <code>port</code>. Streamable HTTP also supports setting <code>stateful_mode</code>.
```

##### SSE (Deprecated, use StreamableHTTP)
SSE is deprecated and streamable HTTP should be used instead, but settings remain for configuring SSE transport.

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

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/config-file.mdx#L176 

The suggested change is more direct, uses the imperative mood for instructions, and provides a clearer reason for the settings' existence.

```suggestion
SSE is deprecated. Use streamable HTTP instead. The settings for the SSE transport remain for backward compatibility.
```

| 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` | `5000` (default) | `u16` | The port to bind to |

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

### Auth

Expand Down Expand Up @@ -226,6 +227,7 @@
- profile
```


### Telemetry

| Option | Type | Default | Description |
Expand Down Expand Up @@ -272,11 +274,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

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 @@ -290,6 +292,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 notice on line 295 in docs/source/config-file.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/config-file.mdx#L295 

Use the present tense instead of the future tense for descriptions.

```suggestion
This configuration file sets up Streamable HTTP transport, enables introspection, and makes all operations 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