Which AI tools work with MCP Gateway?

Claude Desktop, Cursor (v0.48.0+), Windsurf, VS Code Copilot, and any MCP-compatible AI platform. The Router uses Streamable HTTP transport.

Can AI models execute arbitrary GraphQL queries?

By default, no. The MCP Gateway exposes only operations from your configured directory. You can enable arbitrary operations with `enable_arbitrary_operations` if your use case requires it.

How do I make operations understandable to AI models?

Add a docstring to each operation file using the September 2025 GraphQL spec. The Router uses this as the tool description that AI models read when discovering available tools.

Can I prevent AI from running mutations?

Yes. Set `exclude_mutations: true` in the MCP configuration to expose only queries.

How do I handle authentication?

The Router forwards most client headers to the GraphQL execution layer. Use standard header-based authentication or the built-in OAuth 2.1 support for JWT-based auth and multi-level scope enforcement.

MCP Gateway | Secure AI Access to GraphQL | WunderGraph Cosmo

Q: What MCP specification does Cosmo support?

The latest MCP specification with Streamable HTTP transport.

The problem

AI access to APIs needs guardrails

Exposing your GraphQL schema directly to AI gives them the keys to everything. Building custom integrations per platform multiplies maintenance work.

AI models can execute arbitrary queries against your schema

Without a control layer, AI systems can access any data your schema exposes, including sensitive fields your integration was not designed to reach.

Each AI platform needs its own integration code

Custom REST APIs, platform-specific adapters, and separate documentation for each AI tool create compounding maintenance overhead as more platforms emerge.

Compliance teams cannot audit AI data access

Without operation-level control, there is no definitive list of what data AI systems can request. Compliance sign-off requires that list.

Our solution

Predefined operations as MCP tools

The Cosmo Router implements an MCP server. It loads GraphQL operation files from a directory, validates them against your schema, and exposes them as tools AI models can discover and execute.

How MCP Gateway works

Write GraphQL operation files. Add docstring descriptions using the September 2025 GraphQL spec. The description becomes the tool description AI models see.
Enable MCP in the Router config. Point to the operations directory. Optionally exclude mutations for read-only access.
AI tools connect to the MCP endpoint. They discover available operations as tools with their descriptions and JSON schema inputs.
AI models call operations with appropriate parameters. The Router validates, executes against your schema, and returns structured data.
Most client headers forward to the GraphQL execution layer. Use standard header authentication or the built-in OAuth 2.1 support.

One endpoint. Every MCP-compatible AI platform. Predefined operations only.

MCP Gateway

Before & After

Before Cosmo	With Cosmo
Custom integration code for each AI platform	Single MCP endpoint works with all MCP-compatible AI tools
Risk of AI executing arbitrary, harmful queries	Only predefined, validated operations are exposed by default
External documentation required for AI to understand APIs	Self-documenting operations with embedded descriptions
Separate AI-safe APIs built alongside real APIs	Same GraphQL API with controlled operation exposure

Built-in tools

MCP server built-in tools

execute_operation_* — For each operation in your directory, the server generates a corresponding tool with the pattern execute_operation_<operation_name>.
get_operation_info — Retrieves detailed information about a specific operation including its input schema and execution guidance.
get_schema — Provides the full GraphQL schema as a string. Only available when expose_schema is enabled.
execute_graphql — Executes arbitrary queries. Only available when enable_arbitrary_operations is enabled.

How MCP Gateway works in Cosmo Router

01

Docstring = tool description.

Define

Write `.graphql` operation files. Add docstrings using the September 2025 GraphQL spec. The docstring becomes the tool description AI models read to understand when and how to use the operation.

02

YAML config. Stateless mode.

Configure

Enable MCP in the Router configuration. Point to the operations directory. Set `exclude_mutations: true` for read-only access. Configure stateless mode for scalable deployments.

03

All MCP-compatible platforms.

Connect

AI tools connect to the MCP endpoint. They discover available operations as tools, read descriptions and JSON schema inputs, and understand what each operation does.

04

Validated. Federated. Controlled.

Execute

AI calls operations with parameters. The Router validates the request, executes against your federated graph, and returns structured data the AI model can use.

Capabilities

What MCP Gateway provides

Predefined operations, self-documenting tools, and granular access control.

Streamable HTTP transport

Supports the latest MCP specification with Streamable HTTP transport.

JSON schema generation

The Router generates JSON schema for operation variables automatically. AI models understand input requirements without additional documentation.

Self-documenting operations

Embed rich descriptions in operation files using the September 2025 GraphQL spec. AI models read these as tool descriptions.

Stateless mode

Run the MCP server in stateless mode for horizontal scaling and load balancing.

Header forwarding

Most client headers forward to the GraphQL execution layer. Use header-based authentication or the built-in OAuth 2.1 authorization.

Configurable mutation exclusion

Set `exclude_mutations: true` to expose only queries. Create a read-only AI access layer without code changes.

Connect your first AI model to GraphQL

Enable MCP in the Router, add operation files, connect Claude or Cursor.

Start Free Read the Docs

Give AI models secure, controlled access to your GraphQL API