# Research: Apollo MCP Server for Self-Hosted GraphQL

## Date: 2026-03-27

## Infrastructure Overview

### Router
- **Repo**: [theorchard/graphql-router](https://github.com/theorchard/graphql-router) (Rust, custom Apollo Router)
- **Graph ref**: `graphql-theorchard@qa` (Apollo Studio)
- **Environments**: QA, UAT, Prod (each has its own config yaml)
- **Custom plugins**: `theorchard.require_apollo_client_name` (enforces client name header), `pde.auth_enforcement`
- **Introspection**: enabled on QA (`supergraph.introspection: true`)
- **Supergraph composition**: `rover supergraph compose` using `scripts/supergraph.yaml`, or download from Apollo Studio
- **Local dev binary**: `curl -sSL https://router.apollo.dev/download/nix/latest | sh`

### Subgraphs (16 active)

| Service | Family | QA URL |
|---------|--------|--------|
| graphql-abacus | accounting | qa-graphql-abacus.theorchard.io/graphql |
| graphql-account | user-platform | qa-graphql-account.theorchard.io/graphql |
| graphql-analytics | insights | qa-graphql-analytics.theorchard.io/graphql |
| graphql-audience | audience-development | qa-graphql-audience.theorchard.io/graphql |
| graphql-collaborator | collaborators | qa-graphql-collaborator.theorchard.io/graphql |
| graphql-content-review | content-review | qa-graphql-content-review.theorchard.io/graphql |
| graphql-distribution | vector | qa-graphql-distribution.theorchard.io/graphql |
| graphql-knowledge | insights | qa-graphql-knowledge.theorchard.io/graphql |
| graphql-knowledge-search | data-platform | qa-graphql-knowledge-search.theorchard.io/graphql |
| graphql-neighbouring-rights | neighbouring-rights | qa-graphql-neighbouring-rights.theorchard.io/graphql |
| graphql-participant | product-builder | qa-graphql-participant.theorchard.io/graphql |
| graphql-product | product-builder | qa-graphql-product.theorchard.io/graphql |
| graphql-publishing | publishing | qa-graphql-publishing.theorchard.io/graphql |
| graphql-sr-delivery | sound-recordings | qa-graphql-sr-delivery.theorchard.io/graphql |
| graphql-tax-payment | accounting | qa-graphql-tax-payment.theorchard.io/graphql |
| graphql-user | user-platform | qa-graphql-user.theorchard.io/graphql |

### Other active repos (not archived)
- `graphql-switchboard` (product-builder) — not in federated graph currently
- `graphql-notion` (osp)
- `graphql-gateway` (user-platform) — legacy gateway, separate from router

### Required headers for all requests
```
apollographql-client-name: <client-name>   # enforced by router plugin
authorization: Bearer <JWT>
orchard-identity-id: <uuid>
orchard-identity-uuid: <uuid>
orchard-profile-id: <id>
orchard-profile-type: <type>               # e.g. InsightsProfile
orchard-profile-uuid: <uuid>
```

For introspection only (no auth needed):
```
orchard-user-id: oa:123
orchard-profile-id: some-profile-id
orchard-profile-type: profileType
apollographql-client-name: some-client
orchard-profile-uuid: uuid1234
orchard-identity-id: some-identity-i
```

## Apollo MCP Server

### Version & Availability
- **Latest**: v1.11.0 (2026-03-23)
- **Docker**: `ghcr.io/apollographql/apollo-mcp-server:v1.11.0`
- **Binary**: `curl -sSL https://mcp.apollo.dev/download/nix/latest | sh`
- **Docs**: https://www.apollographql.com/docs/apollo-mcp-server

### Self-Hosted (No GraphOS) Support
Fully supported. No `APOLLO_KEY` or `APOLLO_GRAPH_REF` needed when using:
- `operations.source: local` (`.graphql` files become tools)
- `schema.source: local` + `schema.path` (local schema file)
- Introspection tools (`introspect`, `search`, `validate`, `execute`)

### Transport Modes
- `stdio` — default for binary, connects directly to Claude Code
- `streamable_http` — default for Docker, serves on port 8000, connect via `npx mcp-remote`
- SSE was **removed** in v1.5.0

### Operation Sources
| Source | Requires GraphOS | Description |
|--------|-----------------|-------------|
| `local` | No | `.graphql` files from local paths |
| `introspect` | No | Auto-generated from schema introspection |
| `manifest` | No | Persisted query manifest (JSON) |
| `collection` | Yes | Apollo Studio operation collections |
| `uplink` | Yes | Persisted queries via Apollo Uplink |
| `infer` | Varies | Auto-selects based on available config |

### Introspection Tools
- **`introspect`** — explore schema by type name with depth traversal
- **`search`** — keyword search for types (fewer tool calls than introspect)
- **`validate`** — verify operations against schema without execution
- **`execute`** — run arbitrary GraphQL operations

Both `introspect` and `search` support `minify: true` for compact token-efficient output.

### Key Config Options
- `endpoint` — target GraphQL URL
- `headers` — static headers for all requests (supports `${env.VAR}` expansion)
- `forward_headers` — dynamic header forwarding from MCP clients
- `overrides.mutation_mode` — `none` (default), `explicit`, `all`
- `overrides.descriptions` — override tool descriptions
- `cors` — CORS settings
- `health_check` — health endpoint config
- Hot reload supported for config and operation files

### Connection Approaches

**Option A: Direct to QA router**
- Simplest, tests real federated graph
- Needs VPN + auth tokens
- `endpoint: https://qa-graphql-router.theorchard.io/graphql`

**Option B: Local router → QA subgraphs**
- Run router binary locally with `config-qa.yaml`
- `endpoint: http://localhost:8080/graphql`
- No VPN needed for MCP server (router handles upstream)

**Option C: Direct to single subgraph**
- Skip federation, test one subgraph
- Simplest but loses cross-subgraph queries

## Notion References
- [Techweek Workshop: Local Router Setup](https://www.notion.so/10397177520f80b78f62d6f2e7e5125e) (2024-11)
- [Testing Insights with local graphql router](https://www.notion.so/32d97177520f808ea35fc903a1595dbf) (2026-03-24, most recent)
- [GraphQL Subgraphs Tracker](https://www.notion.so/615c6e51c5734d57a84cd8c279701439)
- [Architectural Discussion: APIs, GraphQL and Internal Access](https://www.notion.so/28697177520f8061b59ac9101b4deb5a)