kaiva BRIDGE
GUIDE

How to turn a GraphQL API into an MCP server

Updated

Paste your GraphQL endpoint into Kaiva Bridge, a managed MCP cloud platform. Bridge reads the schema through introspection and turns each query into an MCP tool, with the query's arguments as the tool's inputs and the fields it returns chosen for you. Switch on the tools you want, deploy, and add the server's address to Claude, ChatGPT, Cursor or any other MCP client. Mutations and subscriptions are not offered as tools.

Start freeRead the docs

Step by step

  1. Create a free accountSign up at app.kaiv.ai. No card is needed.
  2. Paste the endpointChoose New server, then REST API, then the GraphQL tab, and paste the address your API answers at, often ending in /graphql. If the API needs a key, add it under More options: a bearer token, a username and password, a header such as X-API-Key, or a query parameter.
  3. Test and introspectClick Test and introspect. Bridge sends the standard introspection query and lists one tool for each query in the schema, all switched off.
  4. Choose the tools and deploySwitch on the queries your AI needs and click Deploy server. Your server is live at an address on api.kaiv.ai.
  5. Add it to your AI clientCopy the address from the Connect tab and add it to your client. Claude and ChatGPT sign in with your Kaiva account, so no key is needed.

The same from a terminal. The token is piped in, so it stays out of your shell history. For an API that needs no key, leave out printf … | and --secret-stdin:

Terminal
npx @kaiva/bridge login
printf %s "$API_TOKEN" | npx @kaiva/bridge push shop-graphql --graphql https://api.example.com/graphql --secret-stdin
npx @kaiva/bridge install shop-graphql --client cursor

What Bridge generates from your schema

Take a schema with two queries, product(id: ID!) and products(first: Int, category: String). Bridge offers two tools, product and products. The tool product has one required input, id. Each tool's description is the field's own description followed by what it returns, for example "One product by its id. Returns Product."

Your AI never writes GraphQL. When it calls product with the id p_42, Bridge sends an operation generated from the schema, and your AI's values travel only as GraphQL variables:

Sent to your API
query Bridge($id: ID!) { product(id: $id) { id name price category { id name } } }

variables: { "id": "p_42" }

Which fields come back

The fields each tool returns are chosen when Bridge reads the schema: the result's own fields, and nested objects up to two levels below it, at most 40 fields in all. A field that needs arguments of its own is left out, so Bridge never has to invent a value. For a union, Bridge asks for the type name and the fields of each member.

If the API answers with GraphQL errors and no data, the tool call fails with the API's own error messages, so your AI can correct its inputs and try again. Data that comes back alongside partial errors is returned together with those errors.

When the schema changes, read it again with Introspect on the server's Source tab, or run the same push command again: a push with the same name reuses the server and reads the source again.

If Bridge cannot read the schema

Introspection is turned off. Many production GraphQL APIs disable it. Bridge says so; allow introspection for the key Bridge uses, then try again.

Depth or complexity limits. If the API refuses the introspection query for its depth, Bridge tries shallower queries, then asks for the query type on its own. A query whose types still come back cut short is left out rather than offered broken. If even the shallowest query is refused, ask the API's owner to exempt introspection from the depth limit.

A 401 or 403. The API wants a credential: add it under More options, or check the one you gave.

Not a GraphQL answer. Check that the address is the GraphQL endpoint itself, often ending in /graphql.

What you need

A GraphQL endpoint that Bridge can reach over the internet, with introspection allowed for the key Bridge uses. Bridge reads up to 300 queries from one schema; switch on only the ones your AI needs, since every tool you switch on is described to your AI.

Free includes 10 MCP servers, 200,000 tool calls a month and 200 pages of documents, with no card.

Other ways to do it

  • Apollo MCP ServerApollo publishes an open-source MCP server that serves GraphQL operations, including ones you write yourself, as tools. You configure and run it yourself.
  • A server with one query toolSome open-source MCP servers give the AI a single tool that sends any GraphQL query it writes. One tool covers the whole schema, and the AI writes each query itself.
  • Write one with an MCP SDKThe official TypeScript and Python SDKs let you write each tool and its query by hand. That gives full control, at the cost of writing and maintaining the code.

Questions

Can the AI run mutations?
No. Only queries become tools. Mutations and subscriptions are never offered.
Does my AI write GraphQL?
No. Each tool's operation is generated from your schema when Bridge reads it. Your AI only supplies values for the query's arguments, which are sent as GraphQL variables.
Which credentials can I use?
A bearer token, a username and password, a header such as X-API-Key, or a query parameter. It is encrypted at rest, added to each request on Bridge's side and never sent to the AI client.
My API has introspection turned off. What now?
Bridge reads the schema through introspection, so it must be allowed for the key Bridge uses. When it is turned off, Bridge tells you so, with what to change.
Does it work with any GraphQL server?
Bridge talks to the endpoint the standard way, with a POST request and a JSON body, so it does not depend on which GraphQL server the API runs on. The API has to answer the standard introspection query.
Is it free?
Free includes 10 MCP servers, 200,000 tool calls a month and 200 pages of documents, with no card.

Related guides