# mcp-graphql-enhanced

GraphQL gateway for AI assistants that prevents context overflow crashes when inspecting complex schemas. Allows targeted graph inspection and endpoint federation.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 6
- Author: letoribo
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/letoribo/mcp-graphql-enhanced
- Updated: 2026-10-22
- HTML: https://affpapa.org/en/nevibecode/mcp/mcp-graphql-enhanced

## What it does

Monolithic schema introspection easily triggers tool size limits when handling large APIs like Neo4j or GitHub. This gateway avoids context exhaustion by letting assistants inspect specific nodes using `typeNames` and control recursion depth with `typeDepth`, keeping queries within reasonable token budgets.

The server enables switching target APIs directly inside `query-graphql` or `introspect-schema` arguments without dropping the active session. It also aggregates multiple endpoints passed as comma-separated addresses, performing object-level deduplication across federated nodes.

Mutations remain blocked out of the box to prevent accidental writes. You must supply the `ALLOW_MUTATIONS` environment variable before any modifying operations can run.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `ENDPOINT`, `HEADERS`, `ALLOW_MUTATIONS`, `NAME`, `SCHEMA`, `MCP_PORT`, `ENABLE_HTTP` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env ENDPOINT=<ENDPOINT> --env HEADERS=<HEADERS> --env ALLOW_MUTATIONS=<ALLOW_MUTATIONS> --env NAME=<NAME> --env SCHEMA=<SCHEMA> --transport stdio mcp-graphql-enhanced -- npx -y @letoribo/mcp-graphql-enhanced
```
Replace <…> with your own values. 2 more environment variables are in the server README

### Codex

**Platform CLI**
```bash
codex mcp add mcp-graphql-enhanced --env ENDPOINT=<ENDPOINT> --env HEADERS=<HEADERS> --env ALLOW_MUTATIONS=<ALLOW_MUTATIONS> --env NAME=<NAME> --env SCHEMA=<SCHEMA> -- npx -y @letoribo/mcp-graphql-enhanced
```
Replace <…> with your own values. 2 more environment variables are in the server README

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "mcp-graphql-enhanced": {
            "command": "npx",
            "args": [
                "-y",
                "@letoribo/mcp-graphql-enhanced"
            ],
            "env": {
                "ENDPOINT": "<ENDPOINT>",
                "HEADERS": "<HEADERS>",
                "ALLOW_MUTATIONS": "<ALLOW_MUTATIONS>",
                "NAME": "<NAME>",
                "SCHEMA": "<SCHEMA>"
            }
        }
    }
}
```
Replace <…> with your own values. 2 more environment variables are in the server README

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "mcp-graphql-enhanced": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@letoribo/mcp-graphql-enhanced"
            ],
            "env": {
                "ENDPOINT": "<ENDPOINT>",
                "HEADERS": "<HEADERS>",
                "ALLOW_MUTATIONS": "<ALLOW_MUTATIONS>",
                "NAME": "<NAME>",
                "SCHEMA": "<SCHEMA>"
            }
        }
    }
}
```
Replace <…> with your own values. 2 more environment variables are in the server README

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e ENDPOINT=<ENDPOINT> -e HEADERS=<HEADERS> -e ALLOW_MUTATIONS=<ALLOW_MUTATIONS> -e NAME=<NAME> -e SCHEMA=<SCHEMA> mcp-graphql-enhanced npx -y @letoribo/mcp-graphql-enhanced
```
Replace <…> with your own values. 2 more environment variables are in the server README

## When to use it
- inspect specific GraphQL types using `typeNames` and `typeDepth` limits
- switch target API endpoints at runtime without resetting server state
- merge multiple independent GraphQL services into a unified federated graph
- pass custom authentication headers directly through tool arguments

## Example prompts
- Run `introspect-schema` for types `User` and `Repository` with `typeDepth` set to 2
- Execute a read query using `query-graphql` with an `Authorization` header passed in arguments
- Query a secondary GraphQL target by providing a different `endpoint` parameter in `query-graphql`

## Similar
- [MCP Toolbox for Databases](https://affpapa.org/en/nevibecode/mcp/googleapis-mcp-toolbox-for-databases.md) — MCP server · ★ 16730
- [PostHog MCP Server](https://affpapa.org/en/nevibecode/mcp/posthog-mcp-server.md) — MCP server · ★ 40459
- [OpenWork MCP Gateway](https://affpapa.org/en/nevibecode/mcp/openwork-mcp-gateway.md) — MCP server · ★ 24271
- [Keploy](https://affpapa.org/en/nevibecode/mcp/keploy.md) — MCP server · ★ 18779
- [Nhost](https://affpapa.org/en/nevibecode/mcp/nhost.md) — MCP server · ★ 9369
- [basebalance.cloud — x402 RPC & MCP gateway](https://affpapa.org/en/nevibecode/mcp/basebalancecloud-x402-rpc-mcp-gateway.md) — MCP server · ★ 7548

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md