Model Context Protocol (MCP)

Evolve includes built-in support for the Model Context Protocol (MCP), an open standard for connecting AI assistants to external tools and data sources. Through MCP, Evolve exposes its e-commerce capabilities as tools that AI agents can discover and invoke. This enables conversational commerce, AI-powered customer support, and autonomous workflows.

From GraphQL to AI tools

The core idea behind Evolve’s MCP implementation is simple: if you can write a GraphQL query, you can create an AI tool. Tools are defined declaratively using GraphQL directives, and everything else (input schemas, type mappings, persisted queries) is generated automatically.

Defining a tool

Annotate any GraphQL operation with @mcpTool and its variables with @mcpToolVariable:

query GetProducts(
  $query: String @mcpToolVariable(description: "Search query for products")
  $limit: Int @mcpToolVariable(description: "Number of results to return")
  $offset: Int @mcpToolVariable(description: "Pagination offset")
) @mcpTool(description: "Search for products by query, with pagination") {
  products(query: $query, limit: $limit, offset: $offset) {
    items {
      name
      slug
      price {
        centAmount
        currencyCode
      }
    }
    total
  }
}

What gets generated

Running pnpm codegen turns these annotated operations into fully typed MCP tool definitions with JSON Schema inputs and persisted document IDs:

export const generatedTools: GeneratedMCPTool[] = [
  {
    name: "get_products",
    description: "Search for products by query, with pagination",
    inputSchema: {
      type: "object",
      properties: {
        query: { type: "string", description: "Search query for products" },
        limit: { type: "integer", description: "Number of results to return" },
        offset: { type: "integer", description: "Pagination offset" },
      },
    },
    documentId: "sha256:abc123...",
    queryString: "query GetProducts($query: String, ...) { ... }",
  },
];

No hand-written tool definitions, no manual schema maintenance. Add a new operation, run codegen, and the tool is available to any MCP client.

How it works

MCP servers in Evolve act as a bridge between AI clients and the GraphQL Federation layer. Because the tools execute GraphQL operations against the same gateway that powers your storefront and mobile app, AI clients get exactly the same data, prices, and business rules as every other channel.

graph TD;
    claude-desktop["Claude Desktop"]-->mcp-server
    ai-assistant["AI Assistant"]-->mcp-server
    cli-tool["CLI Tool"]-->mcp-server
    mcp-server["MCP Server"]-->graphql-gateway["GraphQL Gateway"]
    graphql-gateway-->catalog["Catalog"]
    graphql-gateway-->checkout["Checkout"]
    graphql-gateway-->account["Account"]
    graphql-gateway-->orders["Orders"]
    graphql-gateway-->cms["CMS"]

Key capabilities

• Query security: tools execute as persisted documents registered with GraphQL Hive. The gateway rejects any unregistered query, so the AI can only run pre-approved operations, the same security model as the storefront. See query security.
• Plugin architecture: intercept and customize tool behavior with plugins, for example to handle authentication flows.
• Dual transport: serve tools over HTTP (Streamable HTTP/SSE) for web clients or stdio for desktop clients like Claude Desktop.
• Session management: per-session state with authentication context, store configuration, and automatic token refresh.
• Production-ready: rate limiting, OpenTelemetry metrics, structured logging, and health checks out of the box.

Packages

Package	Description
@evolve-framework/mcp-core	Core library for building MCP servers on top of Evolve’s GraphQL layer
@evolve-platform/mcp-customer	Reference implementation: customer-facing MCP server with product, cart, order, and account tools. Ships with Evolve as a starting point for your own MCP services.

ArchitectureArchitecture of Evolve's MCP implementation, covering transports, sessions, plugins, and request flow.

Creating an MCP serviceHow to create a new MCP service in Evolve using mcp-core.

mcp-coreThe @evolve-framework/mcp-core package, the foundation for building MCP servers in Evolve.

mcp-customerThe mcp-customer service, a customer-facing MCP server exposing product, cart, order, and account tools.

Why MCP on top of GraphQL Federation?Why Evolve builds MCP on top of GraphQL Federation instead of connecting AI directly to vendor APIs.