playbooks

home / mcp / text-to-graphql mcp server

Text-to-GraphQL MCP Server

Transforms natural language into GraphQL queries, with schema loading, validation, execution, history, and MCP compatibility.

Installation
Add the following to your MCP client configuration file.

Configuration

View docs
{
  "mcpServers": {
    "arize-ai-text-to-graphql-mcp": {
      "url": "https://placeholder.example.com/mcp",
      "headers": {
        "MODEL_NAME": "gpt-4o",
        "OPENAI_API_KEY": "sk-...",
        "GRAPHQL_API_KEY": "your_api_key_here",
        "GRAPHQL_HEADERS": "{\"x-api-key\": \"...\"}",
        "GRAPHQL_ENDPOINT": "https://api.example.com/graphql",
        "GRAPHQL_AUTH_TYPE": "bearer",
        "MODEL_TEMPERATURE": "0"
      }
    }
  }
}

You can transform natural language queries into GraphQL queries by running a Text-to-GraphQL MCP server. It bridges human language and GraphQL APIs, letting you build, validate, and execute queries with support for schema introspection, caching, and session history all through MCP clients like Cursor and Claude Desktop.

How to use

Start by running the MCP server locally or in a container, then connect your MCP client to it. You will ask in plain language for what you want, and the server will generate a corresponding GraphQL query, validate it against the loaded schema, and execute it against your GraphQL endpoint if you choose.

What you can do with the MCP server

- Convert natural language requests into GraphQL queries.

- Load and introspect GraphQL schemas so queries are always aligned with the available data.

- Validate generated queries against the active schema before execution.

- Execute queries against your GraphQL endpoint with proper authentication.

- Keep a history of queries across sessions for quick reference.

Connecting via Cursor or Claude Desktop (examples)

Use a configuration block that runs the MCP server through the UV runner, providing the directory to the MCP and the command to start it. The environment variables must include your API keys and endpoint details for GraphQL communication.

{
  "text-to-graphql": {
    "command": "uv",
    "args": [
      "--directory",
      "/path/to/text-to-graphql-mcp",
      "run",
      "text-to-graphql-mcp"
    ],
    "env": {
      "PATH": "/path/to/uv/bin:/usr/bin:/bin",
      "OPENAI_API_KEY": "your_openai_api_key_here",
      "GRAPHQL_ENDPOINT": "https://your-graphql-api.com/graphql",
      "GRAPHQL_API_KEY": "your_api_key_here",
      "GRAPHQL_AUTH_TYPE": "bearer"
    }
  }
}

Starting for testing

Run the MCP server directly for a quick test or execute it as a module when you are in a development environment.

text-to-graphql-mcp

Security and access controls

Keep your OpenAI API key and GraphQL credentials secure. Use environment-specific keys and restrict access to the host running the MCP server. When deploying, prefer server-side secrets management and avoid embedding keys in client configurations.

How to install

Prerequisites you need before starting install include Python tooling and the UV package manager. You will set up UV, install the MCP package, and prepare the environment for running the server.

# Prerequisites
# Install UV (recommended)
curl -LsSf https://astral.sh/uv/install.sh | sh  # macOS/Linux
# Windows:
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Find UV path
which uv

# Typical path examples to set up in MCP config
# macOS/Linux: ~/.local/bin/uv
# Windows: %APPDATA%\uv\bin\uv.exe

Concrete setup steps

Clone the Text-to-GraphQL MCP project, install dependencies, and verify the command help to ensure the server starts correctly.

git clone https://github.com/Arize-ai/text-to-graphql-mcp.git
cd text-to-graphql-mcp
uv sync
uv run text-to-graphql-mcp --help

Alternative installation methods

If you publish or obtain a package, you can install it via a package manager when available.

pip install text-to-graphql-mcp

Quick start for configuration with MCP clients

Configure the MCP client to point to the server using the standard UV-driven command. The directory should point to the MCP location and the command runs the server with UV in the correct environment.

{
  "text-to-graphql": {
    "command": "uv",
    "args": [
      "--directory",
      "/path/to/text-to-graphql-mcp",
      "run",
      "text-to-graphql-mcp"
    ],
    "env": {
      "PATH": "/path/to/uv/bin:/usr/bin:/bin",
      "OPENAI_API_KEY": "your_openai_api_key_here",
      "GRAPHQL_ENDPOINT": "https://your-graphql-api.com/graphql",
      "GRAPHQL_API_KEY": "your_api_key_here",
      "GRAPHQL_AUTH_TYPE": "bearer"
    }
  }
}

Docker deployment

You can run the MCP server in a Docker container and connect MCP clients to it. Provide the API keys and endpoint details as environment variables when starting the container, and connect clients to the running container.

docker build -t text-to-graphql-mcp .
docker run -d \
  --name text-to-graphql-mcp \
  -p 8000:8000 \
  -e OPENAI_API_KEY=your_openai_api_key_here \
  -e GRAPHQL_ENDPOINT=https://your-graphql-api.com/graphql \
  -e GRAPHQL_API_KEY=your_api_key_here \
  -e GRAPHQL_AUTH_TYPE=bearer \
  text-to-graphql-mcp

Observability and maintenance

Monitor MCP server health and query performance to ensure smooth operation. Log outputs and error traces help diagnose schema issues, authentication failures, or invalid queries.

Architecture

The server uses a multi-agent workflow to recognize intent, manage the GraphQL schema, construct queries, validate them, execute against the endpoint, and visualize results.

Available tools

generate_graphql_query

Convert natural language to GraphQL queries.

validate_graphql_query

Validate GraphQL queries against the loaded schema.

execute_graphql_query

Execute GraphQL queries and return formatted results.

get_query_history

Retrieve the history of all queries in the current session.

get_query_examples

Get example queries to understand the system's capabilities.