Quickstart

Get the Cosmo Router MCP Gateway running in 5 minutes. Create your first GraphQL operation and connect an AI tool.

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

• A running Cosmo Router with a configured GraphQL schema (see Router Introduction)
• An AI tool that supports MCP (Claude Desktop, Cursor, Windsurf, VS Code, or similar)

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:

Cursor

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.

Claude Desktop

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.

VS Code

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

http://localhost:5025/mcp

See the VS Code MCP documentation for details.

Windsurf

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.