Quickstart - WunderGraph

Documentation Index

Fetch the complete documentation index at: /llms.txt

Use this file to discover all available pages before exploring further.

This tutorial walks you through enabling MCP on the Cosmo Router, creating your first GraphQL operation, and connecting an AI tool to test it.

Prerequisites

Step 1: Create an Operations Directory

Create a directory to store the GraphQL operations that will be exposed to AI models:

mkdir operations

Step 2: Add Your First Operation

Create a file operations/getUsers.graphql with a named GraphQL operation. The description string becomes the tool description that AI models see:

"""
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
  }
}

Replace the operation above with a query that matches your actual GraphQL schema. The operation must be valid against your schema.

Step 3: Configure the Router

Add the MCP configuration to your config.yaml:

mcp:
  enabled: true
  server:
    listen_addr: 'localhost:5025'
  graph_name: 'my-graph'
  exclude_mutations: true # Start with read-only access
  storage:
    provider_id: 'mcp'

storage_providers:
  file_system:
    - id: 'mcp'
      path: 'operations'

Setting exclude_mutations: true is a good starting point. You can enable mutations later once you’re comfortable with the setup.

Step 4: Start the Router

Start (or restart) your Cosmo Router. You should see a log message indicating the MCP server is listening:

MCP server listening on localhost:5025

Step 5: Connect Your AI Tool

Choose your AI tool and add the MCP server configuration:

Go to Settings > Tools & Integrations > MCP Servers and add:

{
  "mcpServers": {
    "my-graph": {
      "url": "http://localhost:5025/mcp"
    }
  }
}

Requires Cursor v0.48.0+ for Streamable HTTP support.

Go to Settings > Developer > Edit Config and add:

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

Restart Claude Desktop after saving.

Open View > Command Palette > MCP: Add Server and enter the URL:

http://localhost:5025/mcp

See the VS Code MCP documentation for details.

Add to your MCP configuration:

{
  "mcpServers": {
    "my-graph": {
      "serverUrl": "http://localhost:5025/mcp"
    }
  }
}

Step 6: Test It

In your AI tool, try a prompt like:

What tools are available? List all the operations I can use.

The AI model should discover your GetUsers operation (exposed as execute_operation_get_users) and be able to describe it. Then try:

Get all users from the system.

The AI model will call the execute_operation_get_users tool and return the results.

What’s Next?

Create More Operations \
Learn how to write effective operations with descriptions, handle mutations, and organize your operations directory.

Full Configuration \
Explore all configuration options including session handling, storage providers, and advanced settings.

Secure with OAuth \
Add OAuth 2.1 authorization with JWT validation and multi-level scope enforcement.

IDE Setup \
Detailed setup guides for each AI tool, including header forwarding and authentication.