MCP GraphQL Forge

An MCP server that makes GraphQL APIs accessible to AI tools by:

Automatically generating MCP tools from GraphQL schema introspection
Validating parameters and handling errors for reliable AI interactions
Supporting both stdio and HTTP transports for development and production
Caching schema and field selections for consistent performance

✨ Features

Tool Generation: Creates MCP tools from GraphQL schema introspection
Parameter Validation: Multi-layer validation prevents GraphQL errors
Dual Transport: Supports stdio (AI tools) and HTTP (development/testing)
Schema Management: Optional pre-introspection and caching
Authentication: Flexible header configuration for authenticated endpoints [Experimental]

🚀 Getting Started

Quick Start with HTTP Mode (Recommended for Development)

Start the server:

# Start serving it with the Streamable HTTP transport
GRAPHQL_ENDPOINT="https://your-api.com/graphql" npx -y @toolprint/mcp-graphql-forge --transport http --port 3001

Connect with MCP Inspector:

# In another terminal, launch the inspector
npx @modelcontextprotocol/inspector

With authentication:

# Using environment variables for configuration
export GRAPHQL_ENDPOINT="https://api.github.com/graphql"
export GRAPHQL_AUTH_HEADER="Bearer YOUR_TOKEN"
npx @toolprint/mcp-graphql-forge --transport http --port 3001

# Or all in one line
GRAPHQL_ENDPOINT="https://api.github.com/graphql" GRAPHQL_AUTH_HEADER="Bearer YOUR_TOKEN" npx @toolprint/mcp-graphql-forge --transport http --port 3001

Direct AI Integration (Claude/Cursor)

Create an mcp.json in your project root. This will run it in stdio mode.

{
    "mcpServers": {
        "mcp-graphql-forge": {
            "command": "npx",
            "args": [
              "-y",
              "@toolprint/mcp-graphql-forge"
            ],
            "env": {
                "GRAPHQL_ENDPOINT": "https://your-api.com/graphql",
                "GRAPHQL_AUTH_HEADER": "Bearer YOUR_TOKEN"
            }
        }
    }
}

Schema Management

Pre-generate schema:

# Generate schema without starting server
GRAPHQL_ENDPOINT="https://your-api.com/graphql" mcp-graphql-forge introspect

# Start server using pre-generated schema
mcp-graphql-forge --no-introspection --transport http --port 3001

Custom schema location:

# Generate schema in custom location
SCHEMA_PATH="./schemas/my-api.json" mcp-graphql-forge introspect

# Use custom schema location
SCHEMA_PATH="./schemas/my-api.json" mcp-graphql-forge --no-introspection --transport http --port 3001

Force schema regeneration:

# Force regenerate schema even if it exists
mcp-graphql-forge introspect --force

# Regenerate and start server
mcp-graphql-forge --force-introspection --transport http --port 3001

Advanced Configuration

# Multiple custom headers
export GRAPHQL_HEADER_X_API_KEY="your-api-key"
export GRAPHQL_HEADER_X_CLIENT_ID="your-client-id"
mcp-graphql-forge --transport http --port 3001

# Development mode with auto-reload on schema changes
mcp-graphql-forge --transport http --port 3001 --watch

🛠️ How It Works

1. Schema Introspection

🗂️  Building field selection cache for all types...
📊 Generated field selections for 44 types  
💾 Field selection cache contains 44 full selections and 5 minimal selections
Generated 63 tools from GraphQL schema:
  - 30 query tools
  - 33 mutation tools

2. Intelligent Tool Generation

For a GraphQL schema like:

type Query {
  user(id: ID!): User
  articles(filters: ArticleFiltersInput, pagination: PaginationArg): [Article]
}

type Mutation {
  createUser(input: CreateUserInput!): User
}

Fast MCP GraphQL automatically generates:

✅ query_user - with required id parameter validation
✅ query_articles - with optional filtering and pagination
✅ mutation_createUser - with input validation and complete field selections

3. Smart Field Selection

Instead of manual GraphQL query construction:

# ❌ Error-prone manual approach
query {
  articles {
    # Missing required field selections!
    author {
      # Circular reference issues!
    }
  }
}

Fast MCP GraphQL generates optimal queries automatically:

# ✅ Auto-generated with full field selections
query articlesOperation($filters: ArticleFiltersInput, $pagination: PaginationArg) {
  articles(filters: $filters, pagination: $pagination) {
    documentId
    title
    description
    author {
      documentId
      name
      email
      articles_connection {
        nodes { documentId }  # Circular reference handled!
      }
    }
    category {
      documentId
      name
      articles { documentId }  # Cached selection reused!
    }
  }
}

🏗️ Architecture

Caching System

Type-Level Caching: Each GraphQL type's field selection is computed once and reused
Circular Reference Resolution: Intelligent detection with minimal field fallbacks
Consistent Output: Same type always generates identical field selections

Validation Pipeline

JSON Schema Validation: MCP clients validate parameters before execution
Server-Side Validation: Prevents execution with missing required parameters
GraphQL Validation: Final validation at the GraphQL layer

Transport Support

Stdio Transport: For MCP client integration (default)
HTTP Transport: RESTful interface with MCP 2025 Streamable HTTP specification
Session Management: Automatic session handling for HTTP transport

📚 API Reference

CLI Options

mcp-graphql-forge [options]

Options:
  --transport <type>     Transport type: stdio or http (default: stdio)
  --port <number>        Port for HTTP transport (default: 3000)
  --no-introspection     Skip schema introspection (use cached schema)
  --version              Show version number
  --help                 Show help

Environment Variables

Variable	Description	Example
`GRAPHQL_ENDPOINT`	GraphQL API endpoint	`https://api.example.com/graphql`
`GRAPHQL_AUTH_HEADER`	Authorization header	`Bearer token123`
`GRAPHQL_HEADER_*`	Custom headers	`GRAPHQL_HEADER_X_API_KEY=key123`
`SCHEMA_PATH`	Schema cache file path	`./schema.json`
`PORT`	HTTP server port	`3001`

Generated Tool Schema

Each generated tool follows this pattern:

{
  name: "query_user",
  description: "Execute GraphQL query: user",
  inputSchema: {
    type: "object",
    properties: {
      id: { type: "string" }
    },
    required: ["id"]  // Only truly required parameters
  }
}

🧪 Testing

Comprehensive Test Suite

40+ Test Cases: Covering all functionality and edge cases
Real-World Scenarios: Tests against actual GraphQL schemas (Strapi, GitHub, etc.)
Security Testing: Prototype pollution protection and input validation
Performance Testing: Cache efficiency and field selection optimization

# Run all tests
npm test

# Run specific test suites
npm test -- src/__tests__/field-selection-cache.test.ts
npm test -- src/__tests__/server-validation.test.ts
npm test -- src/__tests__/graphql-execution.test.ts

# Coverage report
npm run test:coverage

Integration Testing

# Test with real GraphQL endpoints
GRAPHQL_ENDPOINT="https://countries.trevorblades.com/" npm test

# Test caching performance
npm run test:performance

🛡️ Security

Parameter Validation

Required Parameter Enforcement: Prevents GraphQL variable errors
Null/Undefined Checking: Validates parameter presence and values
Prototype Pollution Protection: Uses secure property checking methods

Schema Security

Input Sanitization: All GraphQL inputs are properly typed and validated
Circular Reference Protection: Prevents infinite recursion in field selections
Header Validation: Secure header handling for authentication

🚀 Performance

Benchmarks

Schema Introspection: ~10ms for typical schemas
Tool Generation: ~5ms with caching enabled
Field Selection: Pre-computed and cached for instant access
Memory Usage: Efficient caching with minimal memory footprint

Optimization Features

Field Selection Caching: Eliminates redundant field selection computation
Schema Caching: Optional schema persistence for faster restarts
Minimal GraphQL Queries: Only requests necessary fields
Connection Pooling: Efficient HTTP client management

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/toolprint/mcp-graphql-forge.git
cd mcp-graphql-forge

# Install dependencies
npm install

# Run tests
npm test

# Start development
npm run dev

Code Quality

TypeScript: Fully typed codebase
ESLint: Consistent code formatting
Vitest: Modern testing framework
100% Test Coverage: Comprehensive test suite

📖 Examples

Real-World Usage

🔸 Strapi CMS Integration

# Connect to Strapi GraphQL API
export GRAPHQL_ENDPOINT="https://your-strapi.com/graphql"
export GRAPHQL_AUTH_HEADER="Bearer YOUR_STRAPI_TOKEN"
mcp-graphql-forge

# Generates tools like:
# - query_articles, query_users, query_categories
# - mutation_createArticle, mutation_updateUser
# - Full field selections with media, relations, and metadata

🔸 GitHub API Integration

# Connect to GitHub GraphQL API
export GRAPHQL_ENDPOINT="https://api.github.com/graphql"
export GRAPHQL_AUTH_HEADER="Bearer YOUR_GITHUB_TOKEN"
mcp-graphql-forge

# Generates tools like:
# - query_repository, query_user, query_organization
# - query_search (with intelligent result type handling)
# - mutation_createIssue, mutation_addComment

🔸 E-commerce Platform

# Connect to Shopify/WooCommerce GraphQL
export GRAPHQL_ENDPOINT="https://your-shop.myshopify.com/api/graphql"
export GRAPHQL_HEADER_X_SHOPIFY_ACCESS_TOKEN="YOUR_TOKEN"
mcp-graphql-forge

# Generates tools for:
# - Product management (query_products, mutation_productCreate)
# - Order processing (query_orders, mutation_orderUpdate)
# - Customer management with full relationship mapping

Custom Schema Example

// Example: Blog Platform Schema
type Query {
  posts(published: Boolean, authorId: ID): [Post]
  post(slug: String!): Post
  authors: [Author]
}

type Mutation {
  createPost(input: CreatePostInput!): Post
  publishPost(id: ID!): Post
}

// Generated Tools:
// ✅ query_posts (published?: boolean, authorId?: string)
// ✅ query_post (slug: string) ← Required parameter enforced
// ✅ query_authors () ← No parameters
// ✅ mutation_createPost (input: CreatePostInput) ← Validated input
// ✅ mutation_publishPost (id: string) ← Required parameter enforced

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🏢 About OneGrep, Inc.

MCP GraphQL Forge is developed and maintained by OneGrep, Inc., a company focused on building developer tools and AI infrastructure.

Issues • Discussions

Made with ❤️ by the OneGrep team

@toolprint/mcp-graphql-forge