From 49f2b4c634b2b21fdfebaf726e014e8f0ed88302 Mon Sep 17 00:00:00 2001 From: Mike Gabriel Date: Mon, 5 Jan 2026 10:24:34 -0500 Subject: [PATCH 1/8] docs(router): document omit_operation_prefix config for MCP tool names Add documentation for the new omit_operation_prefix configuration option that allows cleaner MCP tool names without the execute_operation_ prefix. Related: wundergraph/cosmo#2441 --- docs/router/mcp.mdx | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/router/mcp.mdx b/docs/router/mcp.mdx index bc2606d0..02bea69f 100644 --- a/docs/router/mcp.mdx +++ b/docs/router/mcp.mdx @@ -216,6 +216,7 @@ mcp: exclude_mutations: true enable_arbitrary_operations: false expose_schema: false + omit_operation_prefix: false # When true: GetUser → get_user (no execute_operation_ prefix) # Configure storage providers storage_providers: @@ -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. Security risk: Should only be enabled in secure, internal environments. | `false` | | `expose_schema` | Whether to expose the full GraphQL schema. Security risk: Should only be enabled in secure, internal environments. | `false` | +| `omit_operation_prefix` | When true, MCP tool names are generated without the `execute_operation_` prefix (e.g., `GetUser` → `get_user` instead of `execute_operation_get_user`). Can also be set via `MCP_OMIT_OPERATION_PREFIX` environment variable. | `false` | ## Session Handling @@ -375,6 +377,25 @@ The MCP server converts each operation into a corresponding tool: Operations are converted to snake_case for tool naming consistency. +#### Omitting the Operation Prefix + +By default, all operation tools include the `execute_operation_` prefix. If you prefer shorter, cleaner tool names, enable the `omit_operation_prefix` configuration option: + +```yaml +mcp: + enabled: true + omit_operation_prefix: true +``` + +With this option enabled: + +- Operation name: `GetUsers` → Tool name: `get_users` +- Operation name: `CreateUser` → Tool name: `create_user` + + +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. + + ### Best Practices 1. **Meaningful names**: Give operations clear, action-oriented names that describe what they do. From fb3abd2d364d0eafef92940116fd0131ce9c6e8b Mon Sep 17 00:00:00 2001 From: Mike Gabriel Date: Mon, 5 Jan 2026 12:32:20 -0500 Subject: [PATCH 2/8] docs(router): rename omit_operation_prefix to strip_tool_name_prefix Update config option name per maintainer feedback in wundergraph/cosmo#2441. --- docs/router/mcp.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/router/mcp.mdx b/docs/router/mcp.mdx index 02bea69f..a6933d65 100644 --- a/docs/router/mcp.mdx +++ b/docs/router/mcp.mdx @@ -216,7 +216,7 @@ mcp: exclude_mutations: true enable_arbitrary_operations: false expose_schema: false - omit_operation_prefix: false # When true: GetUser → get_user (no execute_operation_ prefix) + strip_tool_name_prefix: false # When true: GetUser → get_user (no execute_operation_ prefix) # Configure storage providers storage_providers: @@ -238,7 +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. Security risk: Should only be enabled in secure, internal environments. | `false` | | `expose_schema` | Whether to expose the full GraphQL schema. Security risk: Should only be enabled in secure, internal environments. | `false` | -| `omit_operation_prefix` | When true, MCP tool names are generated without the `execute_operation_` prefix (e.g., `GetUser` → `get_user` instead of `execute_operation_get_user`). Can also be set via `MCP_OMIT_OPERATION_PREFIX` environment variable. | `false` | +| `strip_tool_name_prefix` | When true, MCP tool names are generated without the `execute_operation_` prefix (e.g., `GetUser` → `get_user` instead of `execute_operation_get_user`). Can also be set via `MCP_STRIP_TOOL_NAME_PREFIX` environment variable. | `false` | ## Session Handling @@ -377,14 +377,14 @@ The MCP server converts each operation into a corresponding tool: Operations are converted to snake_case for tool naming consistency. -#### Omitting the Operation Prefix +#### Stripping the Tool Name Prefix -By default, all operation tools include the `execute_operation_` prefix. If you prefer shorter, cleaner tool names, enable the `omit_operation_prefix` configuration option: +By default, all operation tools include the `execute_operation_` prefix. If you prefer shorter, cleaner tool names, enable the `strip_tool_name_prefix` configuration option: ```yaml mcp: enabled: true - omit_operation_prefix: true + strip_tool_name_prefix: true ``` With this option enabled: From ff9372b56cb51d2e014074a648fcd47e41c6ed87 Mon Sep 17 00:00:00 2001 From: Mike Gabriel Date: Mon, 5 Jan 2026 12:34:17 -0500 Subject: [PATCH 3/8] docs(router): improve strip_tool_name_prefix description --- docs/router/mcp.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/router/mcp.mdx b/docs/router/mcp.mdx index a6933d65..2f3260da 100644 --- a/docs/router/mcp.mdx +++ b/docs/router/mcp.mdx @@ -238,7 +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. Security risk: Should only be enabled in secure, internal environments. | `false` | | `expose_schema` | Whether to expose the full GraphQL schema. Security risk: Should only be enabled in secure, internal environments. | `false` | -| `strip_tool_name_prefix` | When true, MCP tool names are generated without the `execute_operation_` prefix (e.g., `GetUser` → `get_user` instead of `execute_operation_get_user`). Can also be set via `MCP_STRIP_TOOL_NAME_PREFIX` environment variable. | `false` | +| `strip_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 cleaner tool names for AI models. Can also be set via `MCP_STRIP_TOOL_NAME_PREFIX` environment variable. | `false` | ## Session Handling From 49808f8331bb31d861ffab8f68e2f77d81113f9a Mon Sep 17 00:00:00 2001 From: Mike Gabriel <35150423+shamashel@users.noreply.github.com> Date: Wed, 7 Jan 2026 12:23:17 -0500 Subject: [PATCH 4/8] Clarify 'strip_tool_name_prefix' option in MCP docs Updated the description of the 'strip_tool_name_prefix' option to clarify its effect on tool name length and its optional nature. --- docs/router/mcp.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/router/mcp.mdx b/docs/router/mcp.mdx index 2f3260da..4a1d2f4d 100644 --- a/docs/router/mcp.mdx +++ b/docs/router/mcp.mdx @@ -238,7 +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. Security risk: Should only be enabled in secure, internal environments. | `false` | | `expose_schema` | Whether to expose the full GraphQL schema. Security risk: Should only be enabled in secure, internal environments. | `false` | -| `strip_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 cleaner tool names for AI models. Can also be set via `MCP_STRIP_TOOL_NAME_PREFIX` environment variable. | `false` | +| `strip_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_STRIP_TOOL_NAME_PREFIX` environment variable. | `false` | ## Session Handling From 00ae836f2fc98d7285249e7536f40a8b4433de8e Mon Sep 17 00:00:00 2001 From: Mike Gabriel Date: Thu, 8 Jan 2026 09:50:17 -0500 Subject: [PATCH 5/8] docs(router): rename strip_tool_name_prefix to omit_tool_name_prefix --- docs/router/mcp.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/router/mcp.mdx b/docs/router/mcp.mdx index 4a1d2f4d..051502a1 100644 --- a/docs/router/mcp.mdx +++ b/docs/router/mcp.mdx @@ -216,7 +216,7 @@ mcp: exclude_mutations: true enable_arbitrary_operations: false expose_schema: false - strip_tool_name_prefix: false # When true: GetUser → get_user (no execute_operation_ prefix) + omit_tool_name_prefix: false # When true: GetUser → get_user (no execute_operation_ prefix) # Configure storage providers storage_providers: @@ -238,7 +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. Security risk: Should only be enabled in secure, internal environments. | `false` | | `expose_schema` | Whether to expose the full GraphQL schema. Security risk: Should only be enabled in secure, internal environments. | `false` | -| `strip_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_STRIP_TOOL_NAME_PREFIX` environment variable. | `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 @@ -377,14 +377,14 @@ The MCP server converts each operation into a corresponding tool: Operations are converted to snake_case for tool naming consistency. -#### Stripping the Tool Name Prefix +#### Omitting the Tool Name Prefix -By default, all operation tools include the `execute_operation_` prefix. If you prefer shorter, cleaner tool names, enable the `strip_tool_name_prefix` configuration option: +By default, all operation tools include the `execute_operation_` prefix. If you prefer shorter, cleaner tool names, enable the `omit_tool_name_prefix` configuration option: ```yaml mcp: enabled: true - strip_tool_name_prefix: true + omit_tool_name_prefix: true ``` With this option enabled: From af559365447791bba8fee53ceb7d29b2d50453be Mon Sep 17 00:00:00 2001 From: Mike Gabriel Date: Thu, 8 Jan 2026 10:49:35 -0500 Subject: [PATCH 6/8] docs(router): document collision detection for omit_tool_name_prefix --- docs/router/mcp.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/router/mcp.mdx b/docs/router/mcp.mdx index 051502a1..ccbbe55f 100644 --- a/docs/router/mcp.mdx +++ b/docs/router/mcp.mdx @@ -396,6 +396,10 @@ With this option enabled: 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. + +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. + + ### Best Practices 1. **Meaningful names**: Give operations clear, action-oriented names that describe what they do. From 6ac58f7b739918292a6601bde9f17a78443e0316 Mon Sep 17 00:00:00 2001 From: Mike Gabriel Date: Mon, 26 Jan 2026 02:02:52 -0500 Subject: [PATCH 7/8] docs(router): address review feedback - Remove 'cleaner' language from subsection - Add examples for default (disabled) behavior - Replace arrow character with 'becomes' --- docs/router/mcp.mdx | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/docs/router/mcp.mdx b/docs/router/mcp.mdx index ccbbe55f..5db4bc7a 100644 --- a/docs/router/mcp.mdx +++ b/docs/router/mcp.mdx @@ -379,7 +379,12 @@ 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. If you prefer shorter, cleaner tool names, enable the `omit_tool_name_prefix` configuration option: +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: @@ -387,10 +392,8 @@ mcp: omit_tool_name_prefix: true ``` -With this option enabled: - -- Operation name: `GetUsers` → Tool name: `get_users` -- Operation name: `CreateUser` → Tool name: `create_user` +- `GetUsers` becomes `get_users` +- `CreateUser` becomes `create_user` 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. From f928e6eedc5530c5ad6c0a23bd378843b3fdb606 Mon Sep 17 00:00:00 2001 From: endigma Date: Mon, 26 Jan 2026 17:22:56 +0000 Subject: [PATCH 8/8] Add MCP tool name prefix configuration option --- docs/router/configuration.mdx | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/docs/router/configuration.mdx b/docs/router/configuration.mdx index 927becd6..487d2e4f 100644 --- a/docs/router/configuration.mdx +++ b/docs/router/configuration.mdx @@ -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 | | Enable or disable the MCP server | false | -| MCP_SERVER_LISTEN_ADDR | mcp.server.listen_addr | | The address and port where the MCP server will listen for requests | localhost:5025 | -| MCP_ROUTER_URL | mcp.router_url | | 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 | | The ID of a storage provider to use for loading GraphQL operations. Only file_system providers are supported. | - | -| MCP_SESSION_STATELESS | mcp.session.stateless | | 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 | | The name of the graph to be used by the MCP server | mygraph | -| MCP_EXCLUDE_MUTATIONS | mcp.exclude_mutations | | Whether to exclude mutation operations from being exposed | false | -| MCP_ENABLE_ARBITRARY_OPERATIONS | mcp.enable_arbitrary_operations | | Whether to allow arbitrary GraphQL operations to be executed. Security risk: Should only be enabled in secure, internal environments. | false | -| MCP_EXPOSE_SCHEMA | mcp.expose_schema | | Whether to expose the full GraphQL schema. Security risk: Should only be enabled in secure, internal environments. | false | +| Environment Variable | YAML | Required | Description | Default Value | +| ------------------------------- | ------------------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | +| MCP_ENABLED | mcp.enabled | | Enable or disable the MCP server | false | +| MCP_SERVER_LISTEN_ADDR | mcp.server.listen_addr | | The address and port where the MCP server will listen for requests | localhost:5025 | +| MCP_ROUTER_URL | mcp.router_url | | 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 | | The ID of a storage provider to use for loading GraphQL operations. Only file_system providers are supported. | - | +| MCP_SESSION_STATELESS | mcp.session.stateless | | 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 | | The name of the graph to be used by the MCP server | mygraph | +| MCP_EXCLUDE_MUTATIONS | mcp.exclude_mutations | | Whether to exclude mutation operations from being exposed | false | +| MCP_ENABLE_ARBITRARY_OPERATIONS | mcp.enable_arbitrary_operations | | Whether to allow arbitrary GraphQL operations to be executed. Security risk: Should only be enabled in secure, internal environments. | false | +| MCP_EXPOSE_SCHEMA | mcp.expose_schema | | Whether to expose the full GraphQL schema. Security risk: Should only be enabled in secure, internal environments. | false | +| MCP_OMIT_TOOL_NAME_PREFIX | mcp.omit_tool_name_prefix | | When enabled, MCP tool names generated from GraphQL operations omit the `execute_operation_` prefix. | false | + Example YAML config: