apollo-mcp-server: Instructions file for Codex

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Apollo MCP Server is a Model Context Protocol (MCP) server that exposes GraphQL operations as MCP tools for AI models. It provides a standard way for AI models to access and orchestrate APIs running with Apollo GraphOS.

Build & Test Commands

# Build
cargo build
cargo build --release

# Run all tests
cargo test

# Run a single test
cargo test test_name

# Run tests for a specific crate
cargo test -p apollo-mcp-server

# Linting (CI enforces --deny warnings)
cargo clippy --all-targets -- --deny warnings

# Formatting
cargo fmt
cargo fmt --check

# Generate documentation
cargo doc --no-deps

# Code coverage (requires cargo-llvm-cov)
cargo llvm-cov --all-features --workspace --codecov --output-path codecov.json

Runtime Quick Reference

• Start with config file: cargo run -p apollo-mcp-server -- path/to/config.yaml
• Start from env only: cargo run -p apollo-mcp-server
• Config precedence: APOLLO_MCP_* env overrides YAML values.
• Supported transports: stdio (default) and streamable_http; sse is not supported.
• YAML env expansion supports ${env.VAR} and ${env.VAR:-default}.

Common Config Keys

• Top-level keys: endpoint, transport, operations, schema, introspection, graphos, overrides, headers, forward_headers, health_check, cors, telemetry, logging, server_info, instructions, custom_scalars.
• auth must be nested under transport (not top-level).
• operations.source: infer (default), local, manifest, collection, introspect, uplink.
• schema.source: local or uplink.

Useful Env Vars

• GraphOS mapping:
  • APOLLO_GRAPH_REF -> graphos.apollo_graph_ref
  • APOLLO_KEY -> graphos.apollo_key
  • APOLLO_UPLINK_ENDPOINTS -> graphos.apollo_uplink_endpoints
• Nested config override format: APOLLO_MCP_<SECTION>__<NESTED_KEY>=...
  • Example: APOLLO_MCP_INTROSPECTION__EXECUTE__ENABLED=true