Index of every page on this site: llms.txt
All skills
apollographql avatar

/apollo-mcp-server

@9dda139 official
by Apollo GraphQLapollographql/skills134 stars
14
Run it yourself

Guide for using Apollo MCP Server to connect AI agents with GraphQL APIs. Use this skill when: (1) setting up or configuring Apollo MCP Server, (2) defining MCP tools from GraphQL operations, (3) using introspection tools (introspect, search, validate, execute, explorer), (4) configuring authentication, CORS, health checks, or telemetry, (5) writing Rhai scripts for request lifecycle hooks, (6) defining MCP prompts, (7) troubleshooting MCP server connectivity or tool execution issues, (8) building MCP Apps for interactive UI experiences, (9) deploying Apollo MCP Server to production.

Use this Skill: https://skilld.dev/gh/apollographql/skills/apollo-mcp-server

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencesrhai-scripting.md

≈1.3k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Rhai Scripting

Overview

Apollo MCP Server supports Rhai, a lightweight embedded scripting language for customizing server behavior at runtime. Rhai scripts hook into the request lifecycle to inspect and modify outgoing GraphQL requests without recompiling the server.

Common use cases:

  • Forward authentication headers from MCP requests to your GraphQL endpoint
  • Route requests to different GraphQL endpoints based on request properties
  • Reject requests that fail custom validation

Security: Treat Rhai scripts as trusted code. Scripts can read environment variables, make outbound HTTP requests, and change the endpoint or headers of outgoing GraphQL requests. Restrict write access to the script directory and review script changes before deploying.

Setup

Create a rhai/ directory with a main.rhai entry point:

your-project/
├── config.yaml
└── rhai/
    └── main.rhai

If rhai/main.rhai does not exist, the server starts normally without scripting. Configure a custom directory with:

rhai:
  scripts: /config/rhai

Lifecycle Hook: on_execute_graphql_operation

Called before every outgoing GraphQL HTTP request. Define the function in main.rhai:

fn on_execute_graphql_operation(ctx) {
    ctx.headers["x-custom-header"] = "my-value";
}

Context Object Properties

Property Type Access Description
endpoint String read/write GraphQL endpoint URL for the request
headers HeaderMap read/write HTTP headers for the outgoing request
incoming_request HttpParts read-only Original HTTP request (streamable_http only)
tool_name String read-only MCP tool that triggered this operation
trace_id String read-only Current OpenTelemetry trace ID (32-char hex, or empty)

incoming_request Object

Property Type Description
method String HTTP method (e.g., "POST")
uri String Request URI path (e.g., "/mcp")
headers HeaderMap HTTP headers from the incoming request

Empty when using stdio transport.

Common Patterns

Forward Auth Headers

fn on_execute_graphql_operation(ctx) {
    let token = ctx.incoming_request.headers["authorization"];
    if token != "" {
        ctx.headers["x-forwarded-auth"] = token;
    }
}

Route by Environment

let region = Env::get("GRAPHQL_REGION");

fn on_execute_graphql_operation(ctx) {
    if region == "eu" {
        ctx.endpoint = "https://eu.api.example.com/graphql";
    }
}

Require an Authorization Header

This only checks that the header is present. It does not validate the token. Use transport.auth (see auth.md) for real authentication.

fn on_execute_graphql_operation(ctx) {
    if ctx.incoming_request.headers["authorization"] == "" {
        throw #{
            message: "Missing authorization header",
            code: ErrorCode::INVALID_REQUEST
        };
    }
}

Error Handling

Use throw with a map containing message and code:

Constant Description
ErrorCode::INVALID_REQUEST Client error (missing header, bad input)
ErrorCode::INTERNAL_ERROR Server error (default if no code provided)

Throwing a non-map value logs the value server-side but returns a generic internal error to the client.

Built-in Functions

Env

Function Description
Env::get(name) Read environment variable (returns empty string if unset)

JSON

Function Description
JSON::parse(input) Parse JSON string into Rhai value
JSON::stringify(value) Convert Rhai value to JSON string

Sha256

Function Description
Sha256::digest(input) Hex-encoded SHA-256 hash

Regex

Function Description
Regex::is_match(string, pattern) Test if pattern matches
Regex::replace(string, pattern, replacement) Replace all matches (supports capture groups)
Regex::matches(string, pattern) Return all matching substrings

Http

Function Description
Http::get(url) / Http::get(url, options) GET request, returns Promise
Http::post(url) / Http::post(url, options) POST request, returns Promise

Options: headers (Map), body (String), timeout (Integer, default 30s).

Call .wait() on the promise. Response has .status (Integer), .text() (String), .json() (Dynamic).

Modules

Split scripts into multiple files:

// rhai/main.rhai
import "helpers" as helpers;

fn on_execute_graphql_operation(ctx) {
    helpers::add_auth_headers(ctx);
}

Global Variables

Top-level variables are available to every hook but are copied per invocation. Each hook gets its own copy. A value a hook writes to a variable is discarded when the hook returns. Hooks cannot carry state between requests.

Variables that a top-level closure captured are also copied per invocation, so concurrent calls never read each other's values.

Hooks for concurrent requests run in parallel. Do not write hooks that assume they run to completion before the next request's hook starts.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 alert23d5 checks · Risk HIGH
  • Gen Agent Trust Hub23d

    This skill provides a comprehensive guide for using the Apollo MCP Server. It includes official installation commands that download and execute scripts from the vendor's domain. The skill also processes external GraphQL data, such as schemas and operations, which presents a surface for indirect prompt injection if these sources are attacker-controlled. Additionally, it documents the use of Rhai scripting for runtime customization of server behavior.

  • Socket23d

    No alerts

  • Snyk23d

    Risk: LOW · No issues

  • Runlayer8mo

    2/4 files flagged

  • ZeroLeaks7mo

    1 finding · Score: 82/100

Signed by skilld at 9dda139. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 weeks ago.

Activeupdated 4 weeks ago
What it can do
Runs commands
compatibility
Works with Claude Code, Claude Desktop, Cursor.
metadata
{
  "author": "apollographql",
  "version": "1.3.0"
}
All 1 allowed tools
Bash(rover:*) Bash(npx:*) Read Write Edit Glob Grep
  • MCP
  • API
  • graphql
  • apollo
  • introspection
  • schema
  • claude
  • cursor
  • authentication

README badge

README badge for apollographql/skills/apollo-mcp-server

Exposes GraphQL operations as MCP tools, allowing AI agents to query and mutate GraphQL APIs through the Model Context Protocol. Includes introspection tools (search, validate, execute) and supports operation files, GraphOS collections, and persisted queries with configurable authentication and mutation controls.

Generated from the current SKILL.md.

What transport types does Apollo MCP Server support?
Apollo MCP Server supports streamable_http (recommended for remote and multi-client deployments) and stdio (for clients that launch the server directly). Streamable_http defaults to address 127.0.0.1 and port 8000.
Can I use this with Claude Desktop and Claude Code?
Yes. Apollo MCP Server is compatible with Claude Desktop, Claude Code, and Cursor. Configuration differs slightly: Claude Desktop uses claude_desktop_config.json, while Claude Code uses .mcp.json or the claude mcp add command.
How do I define custom tools from GraphQL operations?
Create GraphQL operation files in a directory (one operation per file) and configure the operations source as local with the directory path. Each named operation automatically becomes an MCP tool. You can also use GraphOS Studio collections or persisted query manifests.
What security settings should I enable for production?
Set mutation_mode to explicit or none (default), use headers configuration for API keys, enable health checks, disable introspection tools, and authenticate requests with Bearer tokens or OAuth. Use persisted queries instead of ad-hoc operations.
What are the four built-in introspection tools?
introspect (explore schema types), search (find types in schema), validate (check operation validity), and execute (run ad-hoc GraphQL operations). All four are disabled by default and must be explicitly enabled in config.yaml.

Generated from the current SKILL.md. These answers refresh after source changes.