CTK Advisors
Back to Blog

GraphQL MCP - Unlocking APIs for AI Assistants

We built a bridge between GraphQL and Claude that lets AI interact with your existing APIs - without special knowledge or code changes.

·4 min read·Chris Knuteson
developmentaiclaudegraphqlmcp

I spent an afternoon levering the strongly typed power of GraphQL into something useful for LLMs

The Problem I Solved

AI assistants are stuck in their own world:

  • (Generally) Can't access your API's
  • No knowledge of your data structures
  • Limited ability to take actions
  • No standard way to bridge the gap

I wanted to empower LLMs to be able to introspect a graphql API as simply as a user/developer can hit /playground.

What I Built

GraphQL MCP is the answer. It sits between Claude and any GraphQL API, self-discovering operations as tools for Claude (or other tool enabled LLMs) to use.

I built it with some core principles:

  • Zero config for schema discovery
  • Type-safe from GraphQL to LLM
  • Security built in from the start
  • No special API modifications needed

It's like a universal adapter - plug in any GraphQL API, and Claude instantly knows how to use it.

How It Actually Works

No magic here. It's leveraging GraphQL's built-in introspection:

  1. On startup, we grab the API's schema
  2. For each query/mutation, we generate a corresponding MCP tool
  3. GraphQL arguments get mapped to tool parameters
  4. When Claude calls a tool, we build and run the right query
  5. Results flow back to Claude in a format it understands

Take a look at the core of it:

// From an AI request to a proper GraphQL query
const query = `
  query ${name}Query${varDefs ? `(${varDefs})` : ""} {
    ${name}${fieldArgs ? `(${fieldArgs})` : ""} ${
  selectionSet ? `{\n${selectionSet}  }` : ""
}
  }
`;

This takes Claude's generic "get me X" and turns it into a proper GraphQL query with all the type safety and structure intact.

Why This Matters

Think about what this enables:

  • Customer service AI with access to your order systems
  • Content management through direct API access
  • Data analysis across internal systems
  • Development tools with codebase knowledge

Instead of AI being isolated, it becomes integrated with your existing stack.

Setting It Up

Stupidly simple:

# Install it
copy the repo <path>

# Run it with your API
GRAPHQL_API_ENDPOINT=https://your-api.com/graphql graphql-mcp-server

Then tell Claude Desktop about it:

{
  "mcpServers": {
    "graphql": {
      "command": "node",
      "args": ["path/to/graphql-mcp-server.js"],
      "env": {
        "GRAPHQL_API_ENDPOINT": "https://your-api.com/graphql"
      }
    }
  }
}

That's it. No code needed. It just works.

Not Screwing Up Security

I built this with the real world in mind:

  • Mutations are off by default - no accidental data changes
  • Whitelist exactly which operations Claude can access (or by default allow them all)
  • API key support for proper authentication
  • Input validation before anything hits your API

You control access granularly:

WHITELISTED_QUERIES="getUser,getProducts,getOrders"
WHITELISTED_MUTATIONS="createOrder,updateProfile"

The Hard Parts

The trickiest aspects of building this:

  • Handling complex GraphQL types without going insane
  • Building queries that don't overfetch and crush your DB
  • Mapping between GraphQL's type system and JSON Schema
  • Making it work without configuration while still being secure

Most painful? Getting the field selection algorithm right. You need enough data to be useful, but not so much that you create N+1 query hell.

What's Coming Next

This is just the start:

  • Better documentation generation
  • Analytics for AI-API interactions
  • Special tooling for common GraphQL systems
  • Other strongly typed APIs (tRPC, Swagger, etc)

The pattern matters more than the code - creating universal bridges between AI and existing systems without rebuilding everything.

Technical Notes

Built with:

  • TypeScript 5+
  • GraphQL 16+
  • JSON-RPC for MCP communication
  • Zero extra runtime dependencies

Check it out: GitHub repo

Want to go deeper? Hit me up at [email protected].

We're building infrastructure for the world where AI and your existing systems work together. Not theoretically or tomorrow - right now.

Share this post