Skip to main content

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.

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​

PackageDescription
@evolve-packages/mcp-coreCore library for building MCP servers on top of Evolve's GraphQL layer
@evolve-platform/mcp-customerReference implementation: customer-facing MCP server with product, cart, order, and account tools. Ships with Evolve as a starting point for your own MCP services.