AI Integration with Model Context Protocol (MCP)

For a high-level introduction, see the MCP Gateway overview. WunderGraph’s MCP Gateway is a feature of the Cosmo Router that enables AI models to interact with your GraphQL APIs using a structured protocol. This guide explains how to configure and use MCP safely and effectively.

What is MCP?

MCP (Model Context Protocol) is a protocol designed to help AI models interact with your APIs by providing context, schema information, and a standardized interface. The Cosmo Router implements an MCP server that exposes your GraphQL operations as tools that AI models can use.

MCP enables AI models to understand and interact with your GraphQL API without requiring custom integration code for each model.

We support only the latest MCP specification 2025-06-18 with Streamable HTTP support.

The Cosmo MCP Server builds on top of the concept of persisted operations (also known as persisted queries or trusted documents). Instead of allowing AI models to execute arbitrary GraphQL operations, it exposes a predefined set of validated and approved operations. This provides a secure and controlled way for AI systems to interact with your data while maintaining tight control over what operations can be executed.

Capabilities Provided by MCP

API Discovery

Make your GraphQL API automatically discoverable by AI models like OpenAI, Claude, and Cursor

Rich Metadata

Provide detailed schema information and input requirements for each operation

Secure Access

Enable controlled, precise access to your data with operation-level granularity

AI Empowerment

Empower AI assistants to work with your application’s data through a standardized interface

Why Use GraphQL with MCP?

The integration of GraphQL with MCP creates a uniquely powerful system for AI-API interactions:

Precise data selection: GraphQL’s nature allows you to define exactly what data AI models can access, from simple queries to complex operations across your entire graph.
Declarative operation definition: Create purpose-built .graphql files with operations tailored specifically for AI consumption. These function as persisted operations (trusted documents), giving you complete control over what queries AI models can execute.
Flexible data exposure: Control exactly which operations and fields are exposed to AI systems with granular precision.
Compositional API design: Build different operation sets for different AI use cases without changing your underlying API.
Runtime safety: GraphQL’s strong typing ensures AI models can only request valid data patterns that match your schema.
Built-in validation: Operation validation prevents malformed queries from ever reaching your backend systems.
Evolve without breaking: Change your underlying data model while maintaining stable AI-facing operations.
Federation-ready: Works seamlessly with federated GraphQL schemas, giving AI access to data across your entire organization.

But what does this mean in practice? How do these technical benefits translate to real-world solutions? To truly understand the transformative power of GraphQL with MCP, let’s explore a common scenario that organizations face when integrating AI with their existing systems.

Real-World Example: AI Integration in Finance

A large financial services company needed to integrate AI assistants into their support workflow—but faced a critical problem: how to allow access to transaction data without exposing sensitive financial details or breaching compliance.

Without proper data boundaries, AI models might inadvertently access or expose sensitive customer information, creating security and compliance risks.

Their existing REST APIs posed three major challenges:

Security vulnerabilities: Their existing REST endpoints contained mixed sensitive and non-sensitive data, making them unusable for AI integration without major restructuring.
Development bottlenecks: Their engineering team estimated 6+ months to create and maintain a parallel “AI-safe” REST API, delaying their AI initiative significantly.
Data governance issues: Without granular control, they couldn’t meet regulatory requirements for tracking and limiting what data AI systems could access.

Using GraphQL and MCP to Define a Safe Access Layer

The team adopted GraphQL with the Model Context Protocol (MCP) to expose only specific operations tailored for AI access:

# AI-safe transaction query with PII and financial details removed
query GetTransactionHistory($accountId: ID!, $last: Int!) {
  account(id: $accountId) {
    transactions(last: $last) {
      id
      date
      merchantNameMasked
      category
      amount
      status
      # No account numbers, routing information, location data, or full merchant details
    }
  }
}

This allowed the company to:

Accelerate compliance review by clearly showing what data AI could access
Avoid duplicating APIs, using GraphQL’s type system and persisted operations
Enforce operational boundaries through schema validation and mutation exclusion
Scale safely by exposing new fields to AI only when explicitly approved

With this model in place, AI assistants could answer questions like “Did my payment to Amazon go through?” using only the approved fields and without touching full account numbers, balance history, or other restricted data.

Outcome

This approach helped the company:

Achieve compliance sign-off in weeks instead of months
Reduce security review effort by 95%
Maintain a single source of truth for internal and AI clients
Future-proof their integration as the API evolved

By combining GraphQL and MCP, they enabled a secure, flexible interface for AI models without having to rewrite their backend.

How It Works

The Cosmo Router server:

Loads GraphQL operations from a specified directory
Validates them against your schema
Generates JSON schemas for operation variables
Exposes these operations as tools that AI models can discover and use
Handles execution of operations when called by AI models

When an AI model interacts with your MCP endpoint:

It discovers available GraphQL operations
Understands input requirements through the JSON schema
Executes operations with appropriate parameters
Receives structured data that it can interpret and use in its responses

Built-in MCP Tools

The MCP server provides several tools out of the box to help AI models discover and interact with your GraphQL API:

Discovery Tools

get_operation_info

Retrieves detailed information about a specific GraphQL operation, including its input schema, query structure, and execution guidance. AI models use this to understand how to properly call an operation in real-world scenarios.

get_schema

Provides the full GraphQL schema as a string. This helps AI models understand the entire API structure. This tool is only available if expose_schema is enabled.

Execution Tools

execute_graphql

Executes arbitrary GraphQL queries or mutations against your API. This tool is only available if enable_arbitrary_operations is enabled, allowing AI models to craft and execute custom operations beyond predefined ones.

execute_operation_*

For each GraphQL operation in your operations directory, the MCP server automatically generates a corresponding execution tool with the pattern execute_operation_<operation_name> (e.g., execute_operation_get_users).

Tool Naming and Schema Generation

The operation execution tools provide a structured and controlled way for AI models to interact with your API:

Tool naming: Tools follow the pattern execute_operation_<operation_name> (with operation names converted to snake_case)
Tool schema: Generated from your GraphQL operation’s variables, ensuring type safety
Tool description: Inherited from your GraphQL operation descriptions, including operation name and additional context
Mutation warnings: Tools for mutation operations include a warning that the operation has side effects

By default, all operations in your specified directory will be exposed as tools. Use the exclude_mutations: true configuration option to prevent mutation operations from being exposed if you want to ensure AI models can only read data.

Configuration

To enable MCP in your Cosmo Router, add the following configuration to your config.yaml:

mcp:
  enabled: true
  server:
    listen_addr: "localhost:5025"
    base_url: "http://localhost:5025/mcp" # Optional: Advertised MCP base URL for SSE clients
  router_url: "https://your-public-router-url.example.com/graphql" # Optional: Used in MCP responses when your router is behind a proxy
  storage:
    provider_id: "mcp" # References a file_system provider defined below
  session:
    stateless: true # Optional: When true, no server-side session state is kept
  graph_name: "my-graph"
  exclude_mutations: true
  enable_arbitrary_operations: false
  expose_schema: false

# Configure storage providers
storage_providers:
  file_system:
    - id: "mcp"
      path: "operations" # Relative to the router binary

Configuration Options

Option	Description	Default
`enabled`	Enable or disable the MCP server	`false`
`server.listen_addr`	The address and port where the MCP server will listen for requests	`localhost:5025`
`server.base_url`	The base URL of the MCP server advertised to LLM clients when SSE is used as primary transport. If unset, it’s derived relative to the router URL.	-
`router_url`	Custom URL to use for the router GraphQL endpoint in MCP responses. Use this when your router is behind a proxy.	-
`storage.provider_id`	The ID of a storage provider to use for loading GraphQL operations. Only file_system providers are supported.	-
`session.stateless`	Whether the MCP server should operate in stateless mode. When true, no server-side session state is maintained between requests.	`true`
`graph_name`	The name of the graph to be used by the MCP server	`mygraph`
`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`

Session Handling

By default, the MCP server runs in stateless mode (session.stateless: true). This avoids scalability issues in load‑balanced or serverless environments where sticky sessions may not be guaranteed. In stateless mode, no session data is retained between requests. In stateless mode, features that rely on long‑lived connections or server‑side session state are unavailable or limited:

No sampling
No elicitation flows
No session resumability
No bidirectional messaging (e.g. Notifications)

Stateful mode (sticky sessions required)

If you set session.stateless: false, the MCP server maintains per‑session state. To ensure all requests for a session reach the same Router instance, configure sticky sessions keyed by Mcp-Session-Id:

The Router returns a unique Mcp-Session-Id response header when a session is established.
Clients must include that value in subsequent requests as the Mcp-Session-Id request header.
Your load balancer or reverse proxy must route requests with the same Mcp-Session-Id to the same instance.

For details, see your load balancer or reverse proxy documentation (e.g., F5 NGINX Plus - MCP Session Affinity).

Session Storage

In the future, we may add persistent session storage (e.g., Redis) to the MCP server. This would enable shared session state across instances and unlock features such as session‑based security, resource subscriptions, and bidirectional messaging without the need to solve it on the load balancer level.

Storage Providers

MCP loads operations from a configured file system storage provider. This allows you to centralize the configuration of operation sources:

storage_providers:
  file_system:
    - id: "mcp"
      path: "operations" # Relative to the router binary

Then reference this storage provider in your MCP configuration:

mcp:
  storage:
    provider_id: "mcp"

A storage provider must be specified to load GraphQL operations.

Setting Up Operations

Create a directory to store your GraphQL operations as specified in your storage.provider_id configuration.
Add .graphql files containing named GraphQL operations.

Each operation file should contain a single named operation along with a description comment that AI models can use to understand its purpose.

Example Query Operation

Create a file operations/getUsers.graphql:

# Returns a list of all users in the system with their basic information
# This is a read-only operation that doesn't modify any data
query GetUsers {
  users {
    id
    name
    email
  }
}

Example Mutation Operation

Create a file operations/createUser.graphql:

# Creates a new user in the system
# Required inputs: name and email
mutation CreateUser($name: String!, $email: String!) {
  createUser(input: { name: $name, email: $email }) {
    id
    name
    email
  }
}

Directory Structure

Here’s an example of how your project directory might be structured:

my-router-project/
├── config.yaml                 # Router configuration file
├── operations/                 # Operations directory (as configured in storage provider)
│   ├── getUsers.graphql        # Query operation
│   ├── createUser.graphql      # Mutation operation
│   ├── getUserById.graphql     # Query with parameters
└── ...

The important points:

The path in your storage_providers.file_system.path should point to the operations directory
All .graphql files in this directory (and subdirectories) will be loaded
Each file should contain a single named GraphQL operation

Operation Naming and Tool Generation

The MCP server converts each operation into a corresponding tool:

Operation name: GetUsers → Tool name: execute_operation_get_users
Operation name: CreateUser → Tool name: execute_operation_create_user

Operations are converted to snake_case for tool naming consistency.

Best Practices

Meaningful names: Give operations clear, action-oriented names that describe what they do.
Add descriptions: Include comments that describe the operation’s purpose, required inputs, and any side effects.
Use explicit types: Define all input variables with explicit types to ensure proper validation.
Create focused operations: Design operations specifically for AI model consumption rather than exposing generic operations.
Security considerations: For mutation operations, add checks and validations to prevent misuse.

Authentication

The MCP server respects the “Authorization” header from MCP clients and forwards them to the router. This allows you to leverage all the authentication and authorization capabilities of your Cosmo Router when AI models interact with your GraphQL API.

By passing authentication headers from AI tools to your GraphQL API, you can maintain consistent security across all API consumers while giving AI models appropriate access to your data.

Installation Guides

The authentication header can be configured in various AI tools and environments:

Claude

Requires latest version of Claude Desktop. Go to Settings > Developer and click on Edit Config. Add the following to the claude_desktop_config.json file:

{
  "mcpServers": {
    "mygraph": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:5025/mcp"]
    }
  }
}

After that, you need to restart Claude Desktop.

Cursor

Requires Cursor v0.48.0+ for Streamable HTTP support.

Go to Settings > Tools & Integrations > MCP Servers and add the following to the mcp.json file:

{
  "mcpServers": {
    "github": {
      "url": "http://localhost:5025/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY" // Optional
      }
    }
  }
}

Windsurf

Windsurf supports Streamable HTTP servers with a serverUrl field:

{
  "mcpServers": {
    "github": {
      "serverUrl": "http://localhost:5025/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY" // Optional
      }
    }
  }
}

VS Code

Click View > Command Palette > "MCP: Add Server" and use the URL http://localhost:5025/mcp to complete the configuration. For more information, see the MCP Servers documentation.

Other MCP-compatible Tools

Other tools and AI models that support the MCP protocol typically provide similar ways to configure authentication headers. Always check the documentation for your specific AI tool for the exact configuration syntax.

Getting Started

🚀 Cosmo Connect

Concepts

Router

Studio

Control Plane

Federation

Deployments and Hosting

​AI Integration with Model Context Protocol (MCP)

​What is MCP?

​Capabilities Provided by MCP

API Discovery

Rich Metadata

Secure Access

AI Empowerment

​Why Use GraphQL with MCP?

​Real-World Example: AI Integration in Finance

​Using GraphQL and MCP to Define a Safe Access Layer

​Outcome

​How It Works

​Built-in MCP Tools

​Discovery Tools

get_operation_info

get_schema

​Execution Tools

execute_graphql

execute_operation_*

​Tool Naming and Schema Generation

​Configuration

​Configuration Options

​Session Handling

​Stateful mode (sticky sessions required)

​Session Storage

​Storage Providers

​Setting Up Operations

​Example Query Operation

​Example Mutation Operation

​Directory Structure

​Operation Naming and Tool Generation

​Best Practices

​Authentication

​Installation Guides

​Claude

​Cursor

​Windsurf

​VS Code

​Other MCP-compatible Tools

AI Integration with Model Context Protocol (MCP)

What is MCP?

Capabilities Provided by MCP

Why Use GraphQL with MCP?

Real-World Example: AI Integration in Finance

Using GraphQL and MCP to Define a Safe Access Layer

Outcome

How It Works

Built-in MCP Tools

Discovery Tools

Execution Tools

Tool Naming and Schema Generation

Configuration

Configuration Options

Session Handling

Stateful mode (sticky sessions required)

Session Storage

Storage Providers

Setting Up Operations

Example Query Operation

Example Mutation Operation

Directory Structure

Operation Naming and Tool Generation

Best Practices

Authentication

Installation Guides

Claude

Cursor

Windsurf

VS Code

Other MCP-compatible Tools