GraphQL

You can run a Python MCP server that indexes a GraphQL schema, embeds per type.field signatures, and serves fast lookups plus on-demand query execution against your GraphQL endpoint. It automates embedding, indexing, and querying so you can guide an LLM to fetch and shape data from a GraphQL service efficiently.

How to use

Start the MCP server locally and point your client to the server’s MCP endpoints. The server exposes two core tools you will use in practice: list_types to search for relevant type.field signatures and run_query to fetch data from your GraphQL endpoint or validate the local schema. You can run the server with a GraphQL endpoint or operate entirely against a local schema for validation and testing. The embedding index is built on startup or when you index a new query, ensuring fast lookups during your session.

How to install

Prerequisites you need to prepare before starting the MCP server:

• Python 3.8+ installed on your system
• A virtual environment tool (recommended)
• Git (optional, for clone if you prefer)

Install and run the server locally

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python3 src/server.py

Run the server with explicit transport or endpoint

Choose your transport or connect to a live GraphQL endpoint. The server defaults to Server-Sent Events (SSE) at 127.0.0.1:8000/sse. You can switch to a streamable HTTP transport or point the server at a remote GraphQL endpoint.

python3 src/server.py
python3 src/server.py --transport sse
python3 src/server.py --transport streamable-http
python3 src/server.py --endpoint https://api.example.com/graphql
python3 src/server.py --endpoint https://api.example.com/graphql --header "Authorization: Bearer $TOKEN"

Environment configuration to enable embeddings

Configure the embeddings service and API keys to enable automatic embedding on startup or reindexing. You typically set these in your environment before launching the server.

export GRAPHQL_EMBED_API_KEY=your_api_key
export GRAPHQL_EMBEDDINGS_URL=https://embeddings.example.org/v1/embed
export GRAPHQL_EMBED_MODEL=text-embedding-3-small
export GRAPHQL_ENDPOINT_URL=https://api.example.com/graphql

If you need extra headers for embedding or endpoint requests, provide them via headers flags or environment variables as described in the setup section.

## Usage patterns

- When you start the server, it ensures the schema index exists. If embeddings are not yet computed, it will generate them in batches and show progress. You can tune batch size via GRAPHQL\_EMBED\_BATCH\_SIZE.

- Use list\_types to discover relevant type.field signatures for your queries. The results guide you to form an appropriate run\_query payload. The tool ranks results using a scoring formula that blends embedding similarity, query intent, and token matches.

## Additional notes

The server stores its index under data/ and keeps it ignored in version control to allow regenerating locally without polluting the repository.

The server provides a minimal set of MCP tools: list\_types for discovery and run\_query for execution. Embeddings use the configured model by default, but you can override with a --model option or environment variables.

## Troubleshooting and tips

If you encounter connectivity or authentication issues with the GraphQL endpoint, verify GRAPHQL\_ENDPOINT\_HEADERS or the --header options you pass when starting the server. Ensure introspection is enabled on the target endpoint if you plan to run against a live GraphQL service.

## Available tools

### list\_types

Fuzzy search over type.field signatures using embeddings; returns a ranked list with optional query and select hints to guide downstream querying.

### run\_query

Execute or proxy a GraphQL query. If an endpoint is configured, the query is sent to the endpoint; otherwise validates against the local schema and returns data as null where resolvers are not available.