@graphql2mcp/lib

Documentation

Library for integrating GraphQL-to-MCP conversion into existing TypeScript MCP servers. Register GraphQL-backed tools on your own McpServer instance alongside your custom tools.

Install

npm install @graphql2mcp/lib

Peer dependency: @modelcontextprotocol/sdk (>= 1.27.1).

npm install @modelcontextprotocol/sdk

Usage

Basic registration

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
import { registerGraphQLTools } from '@graphql2mcp/lib';

const server = new McpServer({ name: 'my-server', version: '1.0.0' });

const result = registerGraphQLTools(server, {
    source: 'schema.graphql',
    endpoint: 'https://api.example.com/graphql'
});

console.log(`Registered ${result.count} tools`);
// result.tools contains metadata about each registered tool

const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
await server.connect(transport);

Mix custom tools with GraphQL tools

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
import { z } from 'zod';
import { registerGraphQLTools } from '@graphql2mcp/lib';

const server = new McpServer({ name: 'hybrid-server', version: '1.0.0' });

// Your own custom tools
server.registerTool(
    'ping',
    {
        title: 'Ping',
        description: 'Health check',
        inputSchema: { message: z.string().optional() }
    },
    ({ message }) => ({
        content: [{ type: 'text', text: `pong: ${message ?? ''}` }]
    })
);

// Add GraphQL tools from an SDL string
registerGraphQLTools(server, {
    source: `
        type Query {
            users(limit: Int): [User!]!
            user(id: ID!): User
        }

        type User {
            id: ID!
            name: String!
            email: String
        }
    `,
    endpoint: 'https://api.example.com/graphql'
});

const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
await server.connect(transport);

With authentication headers

registerGraphQLTools(server, {
    source: 'schema.graphql',
    endpoint: 'https://api.example.com/graphql',
    headers: {
        Authorization: 'Bearer YOUR_TOKEN',
        'X-API-Key': 'your-api-key'
    }
});

From a pre-built schema

If you already have a GraphQLSchema object, pass it directly instead of a source string:

import { buildSchema } from 'graphql';
import { registerGraphQLTools } from '@graphql2mcp/lib';

const schema = buildSchema(`
    type Query {
        hello: String
    }
`);

registerGraphQLTools(server, {
    schema,
    endpoint: 'https://api.example.com/graphql'
});

Mutation configuration

// Expose all mutations
registerGraphQLTools(server, {
    source: 'schema.graphql',
    endpoint: 'https://api.example.com/graphql',
    mutations: 'all'
});

// Expose no mutations (default)
registerGraphQLTools(server, {
    source: 'schema.graphql',
    endpoint: 'https://api.example.com/graphql',
    mutations: 'none'
});

// Expose specific mutations only
registerGraphQLTools(server, {
    source: 'schema.graphql',
    endpoint: 'https://api.example.com/graphql',
    mutations: { whitelist: ['createUser', 'updateUser'] }
});

Options

| Option | Type | Default | Description | | ---------------- | --------------------------- | ------------- | --------------------------------------------------------------------- | | source | string | undefined | SDL string, file path, glob, or introspection JSON path | | schema | GraphQLSchema | undefined | Pre-built GraphQL schema (alternative to source) | | endpoint | string | (required) | GraphQL execution endpoint URL | | headers | Record<string, string> | undefined | HTTP headers for runtime execution | | mutations | MutationMode | 'none' | Mutation exposure mode ('none', 'all', or { whitelist: [...] }) | | depth | number | 3 | Maximum depth for return type field selection | | include | string[] | undefined | Only include these operations | | exclude | string[] | undefined | Exclude these operations | | queryPrefix | string | 'query_' | Prefix for query tool names | | mutationPrefix | string | 'mutation_' | Prefix for mutation tool names | | customScalars | Record<string, z.ZodType> | undefined | Custom Zod schemas for GraphQL custom scalars | | timeout | number | 30000 | Request timeout in milliseconds |

Either source or schema must be provided. If both are given, schema takes precedence.

getGraphQLTools(options)

Generate tools with bound handlers without registering them on a server. Useful when you need full control over registration or want to inspect tools before adding them.

Both getGraphQLTools and registerGraphQLTools are re-exported from @graphql2mcp/core. If you depend on both packages, the functions and types are interchangeable.

import { getGraphQLTools } from '@graphql2mcp/lib';

const { tools, count } = getGraphQLTools({
    source: 'schema.graphql',
    endpoint: 'https://api.example.com/graphql',
    mutations: 'all'
});

for (const tool of tools) {
    console.log(tool.name, tool.operationType);
    // tool.handler(args) executes the GraphQL operation
    // tool.inputSchema, tool.annotations, tool.queryDocument, etc.
}

Each GraphQLToolEntry includes:

| Property | Type | Description | | --------------- | ----------------------------------- | ---------------------------------------------------------- | | name | string | Tool name (e.g. "query_users") | | title | string | Human-readable title (e.g. "Query: users") | | description | string | Tool description | | inputSchema | Record<string, z.ZodType> | Zod shape for input parameters | | annotations | ToolAnnotations | MCP tool annotations (readOnlyHint, destructiveHint, etc.) | | handler | (args) => Promise<CallToolResult> | Async handler that executes the GraphQL operation | | operationType | 'query' \| 'mutation' | Whether this tool wraps a query or mutation | | fieldName | string | The original GraphQL field name | | queryDocument | string | The GraphQL query/mutation document string sent at runtime |

Loading a schema from a live endpoint

Use loadSchemaFromUrl to introspect a live GraphQL endpoint:

import { loadSchemaFromUrl, registerGraphQLTools } from '@graphql2mcp/lib';

const schema = await loadSchemaFromUrl({
    url: 'https://api.example.com/graphql',
    headers: { Authorization: 'Bearer YOUR_TOKEN' }
});

registerGraphQLTools(server, {
    schema,
    endpoint: 'https://api.example.com/graphql',
    headers: { Authorization: 'Bearer YOUR_TOKEN' }
});

Return Value

registerGraphQLTools returns a RegisterGraphQLToolsResult:

interface RegisterGraphQLToolsResult {
    tools: RegisteredToolInfo[];
    count: number;
}

interface RegisteredToolInfo {
    name: string; // e.g. "query_users"
    title: string; // e.g. "Query: users"
    operationType: 'query' | 'mutation';
    fieldName: string; // original GraphQL field name
}

License

MIT