GraphQL.MCP.GraphQLDotNet 0.1.0-alpha.1

graphql-mcp

Expose your GraphQL API as MCP capabilities — one line of code. .NET 10 today, Java Spring next. No proxies. No external processes.

⚠️ Alpha Release — This project is feature-complete for the Hot Chocolate adapter but has not yet been validated against a wide range of real-world schemas. The API surface may change based on community feedback. Production use is at your own discretion.

What is this?

graphql-mcp turns your existing GraphQL API into an MCP server that AI clients (Claude, Copilot, Cursor, Windsurf) can use directly. No schema duplication. No sidecar process. Just your GraphQL API, now speaking MCP.

Supported AI Clients

Supported GraphQL Frameworks

Install

.NET (Hot Chocolate)

dotnet add package GraphQL.MCP.HotChocolate

Java (Spring) — coming soon

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

Quick Start

.NET — 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();

.NET — Full Config

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

    options.AllowMutations = false;
    options.ExcludedFields.Add("internalData");

    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 — 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 from v0.1:

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
└──────────────────────┴──────────────────────┘

See docs/architecture.md for the full design.

Documentation

Roadmap

• .NET Core engine
• Hot Chocolate adapter
• Streamable HTTP transport
• Policy engine (exclusions, naming, depth)
• OpenTelemetry instrumentation
• graphql-dotnet adapter
• Spring GraphQL starter
• MCP Resources (schema summary, type docs)
• MCP Prompts (curated exploration templates)
• OAuth 2.1 metadata support
• stdio transport
• Netflix DGS adapter
• MCP Registry listing

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT — use it however you want.