Skip to content

docs(router): document omit_tool_name_prefix config for MCP tool names #238

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
endigma wants to merge 8 commits into
base: main
Choose a base branch
from
+41 −11
Open

docs(router): document omit_tool_name_prefix config for MCP tool names #238

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
49f2b4c
docs(router): document omit_operation_prefix config for MCP tool names
shamashel Jan 5, 2026
fb3abd2
docs(router): rename omit_operation_prefix to strip_tool_name_prefix
shamashel Jan 5, 2026
ff9372b
docs(router): improve strip_tool_name_prefix description
shamashel Jan 5, 2026
49808f8
Clarify 'strip_tool_name_prefix' option in MCP docs
shamashel Jan 7, 2026
00ae836
docs(router): rename strip_tool_name_prefix to omit_tool_name_prefix
shamashel Jan 8, 2026
af55936
docs(router): document collision detection for omit_tool_name_prefix
shamashel Jan 8, 2026
6ac58f7
docs(router): address review feedback
shamashel Jan 26, 2026
f928e6e
Add MCP tool name prefix configuration option
endigma Jan 26, 2026
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
24 changes: 13 additions & 11 deletions docs/router/configuration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -328,17 +328,19 @@ introspection:

The Model Context Protocol (MCP) server allows AI models to discover and interact with your GraphQL API in a secure way.

| Environment Variable | YAML | Required | Description | Default Value |
| ------------------------------- | ------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------- |
| MCP_ENABLED | mcp.enabled | <Icon icon="square" /> | Enable or disable the MCP server | false |
| MCP_SERVER_LISTEN_ADDR | mcp.server.listen_addr | <Icon icon="square" /> | The address and port where the MCP server will listen for requests | localhost:5025 |
| MCP_ROUTER_URL | mcp.router_url | <Icon icon="square" /> | Custom URL to use for the router GraphQL endpoint in MCP. Use this when your router is behind a proxy; used in MCP responses to provide the real router URL. | - |
| MCP_STORAGE_PROVIDER_ID | mcp.storage.provider_id | <Icon icon="square" /> | The ID of a storage provider to use for loading GraphQL operations. Only file_system providers are supported. | - |
| MCP_SESSION_STATELESS | mcp.session.stateless | <Icon icon="square" /> | Whether the MCP server should operate in stateless mode. When true, no server-side session state is maintained between requests. | true |
| MCP_GRAPH_NAME | mcp.graph_name | <Icon icon="square" /> | The name of the graph to be used by the MCP server | mygraph |
| MCP_EXCLUDE_MUTATIONS | mcp.exclude_mutations | <Icon icon="square" /> | Whether to exclude mutation operations from being exposed | false |
| MCP_ENABLE_ARBITRARY_OPERATIONS | mcp.enable_arbitrary_operations | <Icon icon="square" /> | Whether to allow arbitrary GraphQL operations to be executed. <Warning> Security risk: Should only be enabled in secure, internal environments. </Warning> | false |
| MCP_EXPOSE_SCHEMA | mcp.expose_schema | <Icon icon="square" /> | Whether to expose the full GraphQL schema. <Warning> Security risk: Should only be enabled in secure, internal environments. </Warning> | false |
| Environment Variable | YAML | Required | Description | Default Value |
| ------------------------------- | ------------------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
| MCP_ENABLED | mcp.enabled | <Icon icon="square" /> | Enable or disable the MCP server | false |
| MCP_SERVER_LISTEN_ADDR | mcp.server.listen_addr | <Icon icon="square" /> | The address and port where the MCP server will listen for requests | localhost:5025 |
| MCP_ROUTER_URL | mcp.router_url | <Icon icon="square" /> | Custom URL to use for the router GraphQL endpoint in MCP. Use this when your router is behind a proxy; used in MCP responses to provide the real router URL. | - |
| MCP_STORAGE_PROVIDER_ID | mcp.storage.provider_id | <Icon icon="square" /> | The ID of a storage provider to use for loading GraphQL operations. Only file_system providers are supported. | - |
| MCP_SESSION_STATELESS | mcp.session.stateless | <Icon icon="square" /> | Whether the MCP server should operate in stateless mode. When true, no server-side session state is maintained between requests. | true |
| MCP_GRAPH_NAME | mcp.graph_name | <Icon icon="square" /> | The name of the graph to be used by the MCP server | mygraph |
| MCP_EXCLUDE_MUTATIONS | mcp.exclude_mutations | <Icon icon="square" /> | Whether to exclude mutation operations from being exposed | false |
| MCP_ENABLE_ARBITRARY_OPERATIONS | mcp.enable_arbitrary_operations | <Icon icon="square" /> | Whether to allow arbitrary GraphQL operations to be executed. <Warning> Security risk: Should only be enabled in secure, internal environments. </Warning> | false |
| MCP_EXPOSE_SCHEMA | mcp.expose_schema | <Icon icon="square" /> | Whether to expose the full GraphQL schema. <Warning> Security risk: Should only be enabled in secure, internal environments. </Warning> | false |
| MCP_OMIT_TOOL_NAME_PREFIX | mcp.omit_tool_name_prefix | <Icon icon="square" /> | When enabled, MCP tool names generated from GraphQL operations omit the `execute_operation_` prefix. | false |


Example YAML config:

Expand Down
28 changes: 28 additions & 0 deletions docs/router/mcp.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -216,6 +216,7 @@ mcp:
exclude_mutations: true
enable_arbitrary_operations: false
expose_schema: false
omit_tool_name_prefix: false # When true: GetUser → get_user (no execute_operation_ prefix)

# Configure storage providers
storage_providers:
Expand All @@ -237,6 +238,7 @@ storage_providers:
| `exclude_mutations` | Whether to exclude mutation operations from being exposed | `false` |
| `enable_arbitrary_operations` | Whether to allow arbitrary GraphQL operations to be executed. <Warning>Security risk: Should only be enabled in secure, internal environments.</Warning> | `false` |
| `expose_schema` | Whether to expose the full GraphQL schema. <Warning>Security risk: Should only be enabled in secure, internal environments.</Warning> | `false` |
| `omit_tool_name_prefix` | When enabled, MCP tool names generated from GraphQL operations omit the `execute_operation_` prefix. For example, the GraphQL operation `GetUser` results in a tool named `get_user` instead of `execute_operation_get_user`. This produces shorter tool names and is entirely optional. Can also be set via `MCP_OMIT_TOOL_NAME_PREFIX` environment variable. | `false` |

## Session Handling

Expand Down Expand Up @@ -375,6 +377,32 @@ The MCP server converts each operation into a corresponding tool:

Operations are converted to snake_case for tool naming consistency.

#### Omitting the Tool Name Prefix

By default, all operation tools include the `execute_operation_` prefix:

- `GetUsers` becomes `execute_operation_get_users`
- `CreateUser` becomes `execute_operation_create_user`

When enabled, the `omit_tool_name_prefix` option generates tool names without this prefix:

```yaml
mcp:
enabled: true
omit_tool_name_prefix: true
```

- `GetUsers` becomes `get_users`
- `CreateUser` becomes `create_user`

<Warning>
Enabling this option changes all tool names and may break existing integrations that rely on the `execute_operation_` prefix. Only enable this for new deployments or when you can update all dependent systems.
</Warning>

<Info>
Operations with names that would collide with built-in MCP tools (`get_schema`, `execute_graphql`, `get_operation_info`) automatically retain the `execute_operation_` prefix to prevent conflicts.
</Info>

### Best Practices

1. **Meaningful names**: Give operations clear, action-oriented names that describe what they do.
Expand Down