GraphQL.MCP.HotChocolate 0.1.0

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 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. 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 ships layered discovery surfaces plus MCP prompt workflows:

• tools/list includes per-tool domain, category, tags, and semanticHints annotations
• prompts/list and prompts/get expose reusable exploration, planning, comparison, and safe-call templates
• resources/list and resources/read expose stable overview, domain, tool, and discovery playbook documents
• catalog/list returns grouped domain summaries, semantic hints, and tool metadata for exploration UIs, with stronger grouping for generic wrappers and search-style schemas
• catalog/search returns ranked matches with optional query, domain, category, and tag filters for discovery UIs
• initialize, resources/read graphql-mcp://auth/metadata, and /.well-known/oauth-authorization-server expose OAuth metadata and required scopes for authenticated clients

Use docs/exploration.md and examples/discovery-workflow for a hands-on discovery walkthrough against the sample apps.

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)

Use the latest published version from Maven Central:

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

Java (Netflix DGS)

Use the same latest published graphql-mcp version when the DGS package ships on the stable Java line:

<dependency>
    <groupId>dev.graphql-mcp</groupId>
    <artifactId>graphql-mcp-dgs</artifactId>
    <version>REPLACE_WITH_LATEST_VERSION</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();

var app = builder.Build();
app.UseGraphQLMcp();
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();

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

Full Config (any adapter)

builder.Services.AddHotChocolateMcp(options =>
{
    options.PolicyPreset = McpPolicyPreset.Curated;
    options.PolicyPack = McpPolicyPack.Commerce;
    options.PolicyProfile = new McpPolicyProfile
    {
        Name = "commerce-api",
        IncludedDomains = ["order", "invoice"],
        MinDescriptionLength = 12,
        MaxArgumentComplexity = 60
    };

    options.ToolPrefix = "myapi";
    options.NamingPolicy = ToolNamingPolicy.VerbNoun;

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

    options.Authorization.Mode = McpAuthMode.Passthrough;
    options.Authorization.RequiredScopes.Add("orders.read");
    options.Authorization.Metadata.Issuer = "https://auth.example.com";
    options.Authorization.Metadata.AuthorizationEndpoint = "https://auth.example.com/authorize";
    options.Authorization.Metadata.TokenEndpoint = "https://auth.example.com/token";
    options.Transport = McpTransport.StreamableHttp; // or McpTransport.Stdio
});

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
    policy-preset: curated
    policy-pack: commerce
    policy-profile:
      name: commerce-api
      included-domains:
        - book
      min-description-length: 12
      max-argument-complexity: 60
    tool-prefix: myapi
    naming-policy: verb-noun
    allow-mutations: false
    excluded-fields:
      - internalData
    excluded-domains:
      - admin
    authorization:
      mode: passthrough
      required-scopes:
        - orders.read
      metadata:
        issuer: https://auth.example.com
        authorization-endpoint: https://auth.example.com/authorize
        token-endpoint: https://auth.example.com/token
    transport: streamable-http # or stdio

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 and 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 and stdio)
+----------------------+----------------------+
|  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.

Release Readiness

• The repository is prepared for stable .NET and Java release lines.
• Existing -alpha, -beta, or -rc tags remain prereleases in GitHub Releases, but stable tags without a prerelease suffix become the normal latest release line.
• Spring GraphQL is already published, and the DGS adapter is part of the stable-ready Java surface for the next stable Java tag.

For the full stable release checklist, see docs/releases.md.

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
• MCP prompts for discovery and tool-selection workflows
• MCP resources for catalog overview and domain summaries
• Policy engine (field/type exclusion with globs, domain curation, naming, depth, mutation blocking, complexity gates)
• Selection set field exclusion (nested types)
• OpenTelemetry instrumentation
• Spring GraphQL starter
• Advanced MCP resources (tool summaries, discovery playbooks)
• Advanced MCP prompts (workflow planning, candidate comparison, safe-call prep)
• AI-friendly discovery (domain grouping, semantic hints, grouped catalogs, and catalog search)
• Curated exploration workflow and reusable request assets for the sample apps
• Reusable policy presets and profiles
• Shared policy packs for common schema families and industry domains
• 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.