Quickstart

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
Claude Desktop
VS Code
Windsurf

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.

MCP Gateway Operations

⌘I

Getting Started

Concepts

Cosmo Connect

Cosmo ConnectRPC

Router

Studio

Control Plane

GraphQL / Federation

Deployments and Hosting

Prerequisites

Step 1: Create an Operations Directory

Step 2: Add Your First Operation

Step 3: Configure the Router

Step 4: Start the Router

Step 5: Connect Your AI Tool

Step 6: Test It

What’s Next?

Create More Operations

Full Configuration

Secure with OAuth

IDE Setup

​Prerequisites

​Step 1: Create an Operations Directory

​Step 2: Add Your First Operation

​Step 3: Configure the Router

​Step 4: Start the Router

​Step 5: Connect Your AI Tool

​Step 6: Test It

​What’s Next?

Create More Operations

Full Configuration

Secure with OAuth

IDE Setup

Prerequisites

Step 1: Create an Operations Directory

Step 2: Add Your First Operation

Step 3: Configure the Router

Step 4: Start the Router

Step 5: Connect Your AI Tool

Step 6: Test It

What’s Next?