MCP Gateway - WunderGraph

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.

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

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 and OAuth 2.1 authorization.

AI Empowerment

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

Get Started

Quickstart

Get MCP running in 5 minutes with a minimal configuration and your first operation.

IDE Setup
Connect Claude, Cursor, Windsurf, VS Code, and other AI tools to your MCP server.

Operations
Learn how to create, describe, and organize GraphQL operations for AI consumption.

Configuration
Full reference for all MCP configuration options, sessions, and storage providers.

OAuth 2.1
Secure your MCP server with JWT-based authentication and multi-level scope enforcement.

CLI MCP Server
Use the Cosmo MCP Server in your IDE for schema exploration, dream queries, and more.

Why GraphQL with MCP?

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

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:

  1. Security vulnerabilities: Their existing REST endpoints contained mixed sensitive and non-sensitive data, making them unusable for AI integration without major restructuring.
  2. Development bottlenecks: Their engineering team estimated 6+ months to create and maintain a parallel “AI-safe” REST API, delaying their AI initiative significantly.
  3. 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 MCP to expose only specific operations tailored for AI access. By using operation descriptions (following the September 2025 GraphQL spec), they could provide clear context to AI models about what each operation does and its limitations:

"""
Retrieves recent transaction history for a customer account.
Returns only non-sensitive transaction details suitable for AI assistant responses.
Excludes: account numbers, routing information, precise location data, and full merchant details.
Use this to answer customer questions about recent purchases and payment status.
"""
query GetTransactionHistory($accountId: ID!, $last: Int!) {
  account(id: $accountId) {
    transactions(last: $last) {
      id
      date
      merchantNameMasked
      category
      amount
      status
    }
  }
}

The operation description becomes the tool description that AI models see, helping them understand:

This allowed the company to:

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:

How It Works

The Cosmo Router MCP server:

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

When an AI model interacts with your MCP endpoint:

  1. It discovers available GraphQL operations as tools and their descriptions
  2. Reads the tool descriptions to understand what each operation does, what data it returns, and when to use it
  3. Understands input requirements through the JSON schema
  4. Executes tools with appropriate parameters
  5. 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).