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 1 commit
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
91 changes: 50 additions & 41 deletions docs/source/config-file.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,17 +94,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 @@ -122,46 +122,43 @@
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

Check failure on line 138 in docs/source/config-file.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/config-file.mdx#L138 

YAML indentation should be two spaces per level. This key should be at the same level as `type`.

```suggestion
  address: 127.0.0.1
```
port: 5000

Check failure on line 139 in docs/source/config-file.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/config-file.mdx#L139 

YAML indentation should be two spaces per level. This key should be at the same level as `type`.

```suggestion
  port: 5000
```
stateful_mode: true

Check failure on line 140 in docs/source/config-file.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/config-file.mdx#L140 

YAML indentation should be two spaces per level. This key should be at the same level as `type`.

```suggestion
  stateful_mode: true
```
```
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you address these librarian failures @jcaudle ?

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

##### stdio (default)

| Option | Value | Default Value | Description |
| :----- | :-------- | :------------ | :-------------------------------------------------------------- |
| `type` | `"stdio"` | \* | Use standard IO for communication between the server and client |
##### Type
##### Streamable HTTP
The available fields depend on the value of the nested `type` key. The default type is `stdio`:

| 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. |
| 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 151 in docs/source/config-file.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/config-file.mdx#L151 

Use the code value `streamable_http` for consistency with other mentions in the table.

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

##### Transport Type Specific options

##### SSE (Deprecated, use StreamableHTTP)
Some transport types support further configuration. Streamable HTTP and SSE both allow setting address and port. Streamable HTTP also supoorts setting stateful mode.

Check failure on line 155 in docs/source/config-file.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/config-file.mdx#L155 

Corrected a typo ('supoorts' to 'supports').

```suggestion
Some transport types support further configuration. Streamable HTTP and SSE both allow setting address and port. Streamable HTTP also supports setting stateful mode.
```

| 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 @@ -208,11 +205,11 @@
- profile
```
## 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 @@ -226,6 +223,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 226 in docs/source/config-file.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/config-file.mdx#L226 

Use the present tense for descriptions and ensure parallel verb structure for clarity. The proposed phrasing is also more direct.

```suggestion
This configuration file sets up a Streamable HTTP transport, enables introspection, and uses introspection as the source for all operations:
```

```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 All @@ -242,4 +251,4 @@

```sh
APOLLO_MCP_TRANSPORT__AUTH__SERVERS='[server_url_1,server_url_2]'
```
```