mcp-core

@evolve-framework/mcp-core is the core library for building MCP servers that expose Evolve’s GraphQL operations as AI-consumable tools. It handles transport, sessions, authentication, code generation, and plugin orchestration.

Package entry points

The package provides several entry points for different use cases:

Entry point	Purpose
`@evolve-framework/mcp-core`	Main exports: server, sessions, config, types
`@evolve-framework/mcp-core/codegen`	Code generation pipeline
`@evolve-framework/mcp-core/codegen/tools`	GraphQL-to-MCP tool generation plugin
`@evolve-framework/mcp-core/codegen/persisted-queries`	Persisted document generation
`@evolve-framework/mcp-core/plugins`	Built-in plugins (customer-auth)

Code generation

The core of mcp-core’s developer experience is the code generation pipeline. You define tools using GraphQL directives, and the codegen generates TypeScript tool definitions with JSON schemas automatically.

GraphQL directives

Two directives control how operations become MCP tools:

# Mark an operation as an MCP tool
directive @mcpTool(description: String!) on QUERY | MUTATION

# Describe a variable for the tool's input schema
directive @mcpToolVariable(description: String) on VARIABLE_DEFINITION

Defining a tool

A tool is a GraphQL operation annotated with @mcpTool:

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 produces two outputs:

mcp-tools.generated.ts, an array of tool definitions:

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, ...) { ... }",
  },
  // ...
];

persisted-documents.json, a mapping of document IDs (SHA-256 hashes) to query strings. These are registered with GraphQL Hive at deploy time and act as an allowlist. The gateway rejects any query not in this registry. See Query security for the full security model.

Type mapping

The codegen automatically maps GraphQL types to JSON Schema:

GraphQL type	JSON Schema type
`String`	`string`
`Int`	`integer`
`Float`	`number`
`Boolean`	`boolean`
`ID`	`string`
Enums	`string` with `enum` values
Input objects	`object` with `properties`
Lists	`array` with `items`
Non-null	Added to `required` array

Configuration

MCP servers are configured through environment variables. The base configuration class provides sensible defaults:

Variable	Default	Description
`HTTP_HOST`	`0.0.0.0`	HTTP server bind address
`HTTP_PORT`	`6000`	HTTP server port
`MCP_ENDPOINT_PATH`	`/mcp`	MCP endpoint path
`GATEWAY_ENDPOINT`	`http://localhost:4000/graphql`	GraphQL gateway endpoint URL
`JWT_ISSUER`	`http://localhost:4000`	Expected JWT issuer
`JWT_AUDIENCE`	`http://localhost:4000`	Expected JWT audience
`PROXY_AUTH_ENABLED`	`false`	Allow a trusted proxy to forward a pre-authenticated session via the `X-Access-Token` / `X-Data-Token` / `X-Refresh-Token` headers (takes precedence over `Authorization: Bearer`, skips JWT pre-validation — the gateway still enforces token validity)
`TOKEN_REFRESH_THRESHOLD_SECONDS`	`300`	Refresh tokens this many seconds before expiry
`RATE_LIMIT_MAX`	`100`	Max requests per window
`RATE_LIMIT_WINDOW_SECONDS`	`60`	Rate limit window duration

Built-in plugins

Customer auth plugin

The customer-auth plugin handles login and logout flows by intercepting the customer_login and customer_logout tools. It manages session transitions between guest and authenticated states, including:

Executing login/logout mutations against the GraphQL gateway
Storing new tokens in the session authentication context
Creating a guest session automatically after logout
Token refresh before expiry