The MCP Gateway for GraphQL APIs
The Cosmo Router speaks the Model Context Protocol, so any MCP client can call a set of GraphQL operations you reviewed, and nothing outside it.
System Overview
How the MCP Gateway connects your GraphQL API with AI models
What is an MCP gateway?
An MCP gateway sits between AI clients and your APIs, exposing a controlled set of operations as MCP tools instead of handing the agent your whole schema.
The Model Context Protocol is how AI clients discover and call tools. A gateway implements that protocol on your side, so the agent talks to one endpoint and your backend services stay unchanged.
- A unified access point
- One endpoint every MCP-compatible client connects to, rather than a bespoke integration per AI platform.
- Action-level access control
- Permission attaches to the operation the agent wants to run, not to a route or a server. The agent can call getOrderStatus without being able to call cancelOrder.
- Session and transport handling
- The gateway speaks the protocol, including its version negotiation and its transport, so backend services never learn MCP exists.
- Observability
- Agent calls run through the same request path as the rest of your traffic, so they appear in the same traces and metrics.
- Tool filtering and policy
- You choose which operations become tools. A deliberate ten beats an automatic hundred: the agent keeps a small context, picks the right tool more often, and the surface you defend is a directory you can read.
In Cosmo, the MCP gateway is part of the Router itself. There is no second product to deploy and no separate AI-safe API to maintain.
MCP gateway vs API gateway
| API gateway | MCP gateway | |
|---|---|---|
| Who calls it | An application your team wrote | An AI agent deciding at runtime what to call |
| Unit of access | A route or endpoint | A named operation with typed arguments |
| Protocol | HTTP, REST, gRPC | Model Context Protocol over HTTP |
| Access control | Per route, per client | Per operation, and per OAuth scope on that operation |
| What the caller knows | Whatever your docs say | The tool list, its descriptions, and its JSON schema, read from the gateway |
The two aren't alternatives. An API gateway decides which client reaches which service. An MCP gateway decides which operation an agent may execute, and hands the result back in a shape the model can use.
Is an MCP gateway safer than direct GraphQL access?
| Direct schema access | Through an MCP gateway | |
|---|---|---|
| What the agent can run | Any query the schema permits, including combinations nobody anticipated | Only the operations in your configured directory, validated against the schema when they load |
| Blast radius of a bad call | The whole schema, mutations included | The arguments your operations accept, and nothing else |
| Auth granularity | One token for the whole graph | Per-tool OAuth scopes, taken from @requiresScopes in the schema |
| Read-only | Build and maintain a second, narrower API | exclude_mutations: true |
| What you show a reviewer | The schema, plus an argument | The directory of operation files |
This isn't about encryption or authentication, which you need either way. It's about the size of the surface an agent can act on, and whether you can produce the list.
Give AI Access. Keep Control.
Connect your API with AI models through secure tooling and precise control, unlocking new possibilities for your data
AI Discovery
Make your APIs discoverable by AI models like ChatGPT and Claude, starting with GraphQL.
Operation Control
Expose only approved operations to AI, with full control over what agents can access.
Rich Metadata
Provide detailed schema information and input requirements that AI models can understand and use
Instant Integration
Connect your API with AI platforms like ChatGPT, Claude, and Cursor with minimal configuration
Available AI Tools
Turn your APIs into AI-ready tools — structured, discoverable, and controlled by you.
Automatic Discovery
Enables AI models to autonomously explore your API structure and available operations
Controlled Execution
Operation-specific execution tools that provide secure and governed data access
Rich Metadata
Detailed schema information helps AI models accurately understand your API requirements
Retrieves details about a specific operation
Provides the full GraphQL schema
Executes arbitrary GraphQL operations
Gets a list of all users in the system
Updates user information (mutation operation)
Schema-Aware AI Integration
Cosmo adds rich JSON Schema metadata to your APIs so AI agents understand what each operation does and how to use it safely.
Smart Schema Analysis
Cosmo analyzes your API operations to extract semantic information about what each one does and how it should be used.
Comment Preservation
Cosmo preserves your documentation comments and passes them to AI agents, providing helpful context for every operation.
How It Enhances AI Understanding
This metadata gives AI models the context they need to understand your API structure, parameter types, and validation requirements—helping them generate accurate and valid requests without guesswork.
How it works
Four steps from a GraphQL operation on disk to a tool an agent can call.
01
Define
Write .graphql operation files. Add a docstring to each one using the September 2025 GraphQL spec. The docstring becomes the tool description AI models read to understand when and how to use the operation.
02
Configure
Enable MCP in the Router configuration and point it at the operations directory. Set exclude_mutations: true for read-only access. Configure stateless mode for horizontal scaling.
03
Connect
AI clients connect to the MCP endpoint. They discover the available operations as tools, then read the descriptions and JSON schema inputs to understand what each one does.
04
Execute
The client calls an operation with parameters. The Router validates the request, executes it against your federated graph, and returns structured data the model can use.
What the agent can call, and what it can't
Every tool the agent sees maps to one reviewed .graphql file. There is no tool for anything else.
Agent session
Pull the recent orders for customer 4821 so I can answer this ticket.
tools/call execute_operation_get_customer_orders
{ "customerId": "4821" }
- ord_9f21 · delivered
- ord_9c07 · in transit
- ord_98b3 · refunded
Now change that customer's email address.
No tool is available for that. The agent cannot read the schema, cannot compose a query, and sees no mutation tools.
The config behind it
mcp:
enabled: true
expose_schema: false
enable_arbitrary_operations: false
exclude_mutations: true
storage:
provider_id: ai-operations- expose_schema: false
- No full-schema introspection. The agent never sees the fields you did not publish.
- enable_arbitrary_operations: false
- No arbitrary GraphQL. Both of these are off by default, and turning either on undoes the safelist.
- exclude_mutations: true
- Queries only. It defaults to
false, so set it when you want a read-only agent.
What teams use it for
Four problems the gateway solves, and the configuration behind each one.
Read-only access to production data
An analyst agent that can answer "how many orders shipped last week" can usually also cancel them, because it is the same connection.
Set exclude_mutations and the gateway exposes queries only. No second API, no read replica, no code change in any subgraph.
exclude_mutations: true
Per-tool scopes instead of one blanket token
Give an agent a single token for the whole graph and every tool it holds carries every permission you granted.
The Router reads @requiresScopes from your federated schema and enforces the scopes per tool. An agent calling a read tool needs the read scope, and nothing more. OAuth 2.1 is off by default; once on, every request carries a JWT and scopes are enforced additively at five levels, from session initialization down to the individual tool.
@requiresScopes
Step-up authorization for privileged operations
An agent that opens a session with write permissions it needs twice a day has write permissions all day.
Step-up authorization lets an agent start on a baseline scope and ask for more only when it calls a tool that needs them. Cosmo enforces this server-side today. Client support is the catch: as of April 2026 the docs name Claude Code and the MCP TypeScript SDK as unable to re-authenticate on a 403 insufficient_scope, which is what makes step-up work end to end.
403 insufficient_scope
Curated operations as the safelist
The reviewed-operation list is the whole access policy, so it should live where the rest of your graph changes live.
Tools come from .graphql files on disk, loaded through a file_system storage provider and validated against the schema when they load. They go through normal code review, not a separate policy system. Add a field to the schema and no agent can reach it until somebody writes an operation that selects it.
file_system storage provider
Questions about AI agent access
What is an MCP gateway?
An MCP gateway sits between AI clients and your APIs, exposing a controlled set of operations as tools an agent can call. Instead of handing an agent your whole schema, you publish a specific list. The gateway handles the Model Context Protocol so your backend services do not have to.
How is an MCP gateway different from an API gateway?
An API gateway routes requests from applications to endpoints. An MCP gateway serves autonomous agents calling tools, so the unit of access control is the operation, not the route. The question shifts from "can this client reach /orders" to "can this agent execute cancelOrder, for this user, right now".
Is an MCP gateway safer than giving an agent direct access to a GraphQL API?
Direct access means the agent can run any query the schema permits, including combinations you never anticipated. A gateway narrows that to operations you wrote and reviewed. The difference is not encryption or authentication, both of which you should have either way. It is the size of the surface an agent can act on.
How do you decide what an AI agent is allowed to do?
You write GraphQL operation files and point the Router at that directory. Each one becomes a tool. Anything you did not write is not available. Because they are normal GraphQL operations, they go through the same review as any other change to your graph, rather than living in a separate policy system.
Can an AI agent run arbitrary queries against your schema?
Not by default. The gateway exposes only the operations in your configured directory. Two settings widen that, and both are off by default: enable_arbitrary_operations turns on the execute_graphql tool, and expose_schema turns on get_schema. Either one hands the agent back the surface the safelist was there to remove.
Can you stop an AI agent from running mutations?
Yes. Set exclude_mutations: true in the MCP configuration and only queries are exposed. It defaults to false, so set it explicitly if you want read-only. This gives you a read-only agent without building a second API.
How do you scope MCP tool permissions per operation instead of per server?
Scopes come from your schema. The Router reads @requiresScopes directives on the fields an operation selects and enforces the resulting scope set on that tool, so each tool carries only the permissions its operation needs. Scope claims must arrive as a space-separated string; array-format claims are not supported.
Can prompt injection reach your backend through an MCP gateway?
A gateway does not stop an agent being manipulated. What it does is limit what a manipulated agent can execute. An injected instruction can only call operations you published, with the arguments those operations accept, so the blast radius is whatever your operation list allows rather than whatever the schema allows. Keep the list tight.
Do your backend services need to support MCP?
No. Your subgraphs stay GraphQL and do not know MCP exists. The Cosmo Router speaks the protocol on their behalf, including as the specification changes, so protocol churn is the Router problem rather than your services.
Do you need to build a separate AI-safe API?
No. That is the usual workaround: a second, narrower API built alongside the real one, then maintained in parallel forever. The MCP Gateway exposes a controlled slice of the graph you already run.
What MCP specification version does Cosmo support?
The Router advertises protocol version 2026-07-28 by default. In session mode it negotiates 2025-11-25 or older, so a client on an earlier revision still connects rather than being refused. Transport is Streamable HTTP.
Can an AI agent subscribe to live data through the gateway?
No. The MCP gateway exposes queries and mutations as tools, and subscriptions are not supported. A tool call is one request and one response, which does not map onto a long-lived stream. For streaming, use the Router subscription transports directly.
Read more on AI agent access
How the Cosmo Router decides what an AI agent is allowed to run, and what that looks like in practice.
Controlling what an agent can execute
Authorization and scopes
Architecture and cost
- GraphQL Is the API Layer AI Agents Actually Need
- How to Connect REST and gRPC APIs to GraphQL Federation with Cosmo Connect
- Why MCP Is the Ceiling, Not the Foundation of Enterprise AI Agent Architecture
- The Impact of MCP and LLMs on Software Development
- Cosmo MCP: Agent Mode for GraphQL Federation in Your IDE
- Why Your LLM Bill Exploded Overnight (and How to Regain Control)
- RAG Cost Control for AI Agents: How to Prevent AI Spend Drifts
Ready to connect your API to AI?
Get started with MCP in minutes and unlock the full potential of your APIs with safe, structured AI access.
