GraphQL.MCP.GraphQLDotNet 0.1.0-alpha.4

graphql-mcp

MCP capabilities for every GraphQL server — Hot Chocolate, graphql-dotnet, Spring GraphQL, and more. Cross-framework curation, policy controls, and AI-friendly capability discovery.

What is this?

graphql-mcp is a cross-framework GraphQL AI capability layer. It turns your existing GraphQL API into an MCP server that AI clients (Claude, Copilot, Cursor, Windsurf) can use directly — with curation, policy controls, and safety built in.

No schema duplication. No sidecar process. Just your GraphQL API, now speaking MCP.

Why graphql-mcp?

Some frameworks are adding native MCP support (e.g., Hot Chocolate 16). graphql-mcp goes further:

Use native MCP when your framework ships it and it covers your needs. Use graphql-mcp when you need cross-framework support, advanced curation, or operate across multiple GraphQL backends.

Discovery

graphql-mcp now ships two lightweight discovery surfaces:

• tools/list includes per-tool domain, category, and tags annotations
• catalog/list returns grouped domain summaries and tool metadata for exploration UIs

Supported AI Clients

Supported GraphQL Frameworks

Install

Hot Chocolate

dotnet add package GraphQL.MCP.HotChocolate

graphql-dotnet

dotnet add package GraphQL.MCP.GraphQLDotNet

Java (Spring)

<dependency>
    <groupId>dev.graphql-mcp</groupId>
    <artifactId>graphql-mcp-spring-boot-starter</artifactId>
    <version>0.1.0-alpha.3</version>
</dependency>

Quick Start

Hot Chocolate — Zero Config

using GraphQL.MCP.HotChocolate;

var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddGraphQLServer()
    .AddQueryType<Query>();

builder.Services.AddHotChocolateMcp();  // one line

var app = builder.Build();
app.UseGraphQLMcp();                     // maps /graphql + /mcp
app.Run();

graphql-dotnet — Zero Config

using GraphQL.MCP.AspNetCore;
using GraphQL.MCP.GraphQLDotNet;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddGraphQL(b => b
    .AddSchema<MySchema>()
    .AddSystemTextJson());

builder.Services.AddGraphQLDotNetMcp();  // one line

var app = builder.Build();
app.UseGraphQL("/graphql");
app.UseGraphQLMcp();                      // maps /mcp
app.Run();

Full Config (any adapter)

builder.Services.AddHotChocolateMcp(options =>   // or AddGraphQLDotNetMcp
{
    options.ToolPrefix = "myapi";
    options.MaxOutputDepth = 3;
    options.NamingPolicy = ToolNamingPolicy.VerbNoun;

    options.AllowMutations = false;
    options.ExcludedFields.Add("internalNotes");
    options.ExcludedTypes.Add("AdminPanel");

    options.Authorization.Mode = McpAuthMode.Passthrough;
    options.Transport = McpTransport.StreamableHttp;
});

Java — Zero Config

@EnableGraphQLMCP
@SpringBootApplication
public class App {
    public static void main(String[] args) {
        SpringApplication.run(App.class, args);
    }
}

Java — Full Config (application.yml)

graphql:
  mcp:
    enabled: true
    tool-prefix: myapi
    max-output-depth: 3
    naming-policy: verb-noun
    allow-mutations: false
    excluded-fields:
      - internalData
    authorization:
      mode: passthrough
    transport: streamable-http

How It Works

GraphQL Schema --> Schema Canonicalization --> Policy Engine --> MCP Tools
                                                                    |
AI Client --> POST /mcp --> Tool Executor --> GraphQL Execution --> Result

1. Introspects your GraphQL schema at startup
2. Canonicalizes operations into a framework-agnostic model
3. Applies policies — field/type exclusions, naming, depth limits, mutation safety
4. Publishes tools as MCP tool descriptors with JSON Schema inputs
5. Executes GraphQL queries when AI clients invoke tools

Safety by Default

Observability

Built-in OpenTelemetry support:

builder.Services.AddOpenTelemetry()
    .WithTracing(t => t.AddSource("GraphQL.MCP"))
    .WithMetrics(m => m.AddMeter("GraphQL.MCP"));

Metrics: mcp.tool.invocations, mcp.tool.errors, mcp.tool.duration

Architecture

+---------------------------------------------+
|  GraphQL.MCP.Abstractions                   |  Contracts (zero deps)
+---------------------------------------------+
|  GraphQL.MCP.Core                           |  Engine (canonicalize, policy, publish, execute)
+---------------------------------------------+
|  GraphQL.MCP.AspNetCore                     |  HTTP transport (Streamable HTTP)
+----------------------+----------------------+
|  GraphQL.MCP.        |  GraphQL.MCP.        |
|  HotChocolate        |  GraphQLDotNet       |  Framework adapters
+----------------------+----------------------+

The core engine is fully framework-agnostic. Adding a new framework adapter means implementing two interfaces: IGraphQLSchemaSource and IGraphQLExecutor.

See docs/architecture.md for the full design.

Claude Desktop Setup

Start your GraphQL MCP server, then add to claude_desktop_config.json:

{
  "mcpServers": {
    "my-graphql-api": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:5000/mcp"]
    }
  }
}

Restart Claude Desktop. Your GraphQL operations will appear as tools.

Documentation

Roadmap

• .NET Core engine (framework-agnostic)
• Hot Chocolate adapter
• graphql-dotnet adapter
• Streamable HTTP transport
• Policy engine (field/type exclusion with globs, naming, depth, mutation blocking)
• Selection set field exclusion (nested types)
• OpenTelemetry instrumentation
• Spring GraphQL starter
• MCP Resources (schema summary, type docs)
• MCP Prompts (curated exploration templates)
• [~] AI-friendly discovery (domain grouping and grouped catalogs shipped; semantic hints next)
• OAuth 2.1 metadata support
• stdio transport
• Netflix DGS adapter

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT — use it however you want.