Getting Started with GraphQL MCP#

GraphQL MCP makes it easy to expose GraphQL APIs as MCP (Model Context Protocol) tools that can be used by AI agents and other systems.

Works with ANY GraphQL library: Strawberry, Ariadne, Graphene, graphql-api, or any library using graphql-core.

Installation#

Install GraphQL MCP:

pip install graphql-mcp

Or using UV (recommended):

uv add graphql-mcp

Prerequisites#

GraphQL MCP works with any GraphQL schema from popular libraries:

  • Strawberry - Modern, type-hint based GraphQL
  • Ariadne - Schema-first GraphQL
  • Graphene - Code-first GraphQL
  • graphql-api - Decorator-based GraphQL (recommended for new projects)
  • Any library that produces a graphql-core schema

Your First MCP Server#

Choose your preferred GraphQL library:

With Strawberry#

import strawberry
import uvicorn
from graphql_mcp.server import GraphQLMCP

# 1. Define your GraphQL schema with Strawberry
@strawberry.type
class Query:
    @strawberry.field
    def hello(self, name: str = "World") -> str:
        """Say hello to someone."""
        return f"Hello, {name}!"

    @strawberry.field
    def goodbye(self, name: str = "World") -> str:
        """Say goodbye to someone."""
        return f"Goodbye, {name}!"

# 2. Create schema and MCP server
schema = strawberry.Schema(query=Query)
server = GraphQLMCP(schema=schema._schema, name="Greetings")

# 3. Create and run the HTTP application
app = server.http_app()

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8002)

With Ariadne#

from ariadne import make_executable_schema, QueryType
import uvicorn
from graphql_mcp.server import GraphQLMCP

# 1. Define your GraphQL schema with Ariadne
type_defs = """
    type Query {
        hello(name: String = "World"): String!
        goodbye(name: String = "World"): String!
    }
"""

query = QueryType()

@query.field("hello")
def resolve_hello(_, info, name="World"):
    return f"Hello, {name}!"

@query.field("goodbye")
def resolve_goodbye(_, info, name="World"):
    return f"Goodbye, {name}!"

# 2. Create schema and MCP server
schema = make_executable_schema(type_defs, query)
server = GraphQLMCP(schema=schema, name="Greetings")

# 3. Create and run the HTTP application
app = server.http_app()

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8002)
from graphql_api import GraphQLAPI, field
import uvicorn
from graphql_mcp.server import GraphQLMCP

# 1. Define your GraphQL API with graphql-api
class HelloAPI:
    @field
    def hello(self, name: str = "World") -> str:
        """Say hello to someone."""
        return f"Hello, {name}!"

    @field
    def goodbye(self, name: str = "World") -> str:
        """Say goodbye to someone."""
        return f"Goodbye, {name}!"

# 2. Create GraphQL API and MCP server
api = GraphQLAPI(root_type=HelloAPI)
server = GraphQLMCP.from_api(api, name="Greetings")

# 3. Create and run the HTTP application
app = server.http_app()

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8002)

Save this as server.py and run it:

python server.py

Your MCP server is now running on http://localhost:8002!

What Just Happened?#

  1. Defined a GraphQL API - We created a simple API with two query fields
  2. Created MCP Server - GraphQLMCP.from_api() analyzed the schema and generated MCP tools
  3. Configured HTTP - Set up the HTTP transport for MCP communication
  4. Started Server - Used Uvicorn to serve the MCP endpoints

Testing Your Server#

Using the MCP Inspector#

If you enable the GraphQL HTTP endpoint, you can use the built-in MCP Inspector:

server = GraphQLMCP.from_api(
    api,
    name="Greetings",
    graphql_http=True  # Enable GraphQL and MCP Inspector
)

mcp_app = server.http_app()

Now visit http://localhost:8002/graphql in your browser to access the inspector interface.

Using an MCP Client#

You can also test with any MCP client. Here’s an example using the MCP Python SDK:

from mcp import ClientSession
from mcp.client.stdio import stdio_client

async def test_mcp():
    async with stdio_client() as (read, write):
        async with ClientSession(read, write) as session:
            # Initialize connection
            await session.initialize()

            # List available tools
            tools = await session.list_tools()
            print(f"Available tools: {tools}")

            # Call a tool
            result = await session.call_tool("hello", arguments={"name": "Alice"})
            print(f"Result: {result}")

import asyncio
asyncio.run(test_mcp())

Next Steps#

Now that you have a basic server running, you can:

Common Patterns#

Adding Authentication#

GraphQL MCP supports JWT authentication. For details on authentication configuration, see the graphql-http authentication documentation.

from graphql_mcp.auth import JWTVerifier

jwt_verifier = JWTVerifier(
    jwks_uri="https://your-auth0-domain/.well-known/jwks.json",
    issuer="https://your-auth0-domain/",
    audience="your-api-audience"
)

server = GraphQLMCP.from_api(api, auth=jwt_verifier)

Enabling Both GraphQL and MCP#

To serve both MCP tools and a GraphQL HTTP endpoint with GraphiQL:

server = GraphQLMCP.from_api(
    api,
    graphql_http=True,  # Enables GraphQL endpoint
    name="My API"
)

Learn more about GraphQL HTTP serving.

Controlling Mutations#

server = GraphQLMCP.from_api(
    api,
    allow_mutations=False  # Only expose queries as tools
)

Troubleshooting#

Server won’t start#

Make sure all dependencies are installed:

pip install graphql-mcp graphql-api uvicorn

Tools not appearing#

Check that your GraphQL fields are properly decorated with @field and that they have docstrings. The tool names and descriptions come from your GraphQL schema.

Type errors#

GraphQL MCP automatically maps GraphQL types to Python types. If you encounter type errors, ensure your type hints match your GraphQL schema definitions.

Configuration Forward