Nominal MCP Server

An MCP server for the Nominal hardware test platform. Pull test data, inspect telemetry channels, run analysis, and write results back — from Claude Code, Cursor, or any MCP client, without leaving your editor.

Implements MCP 2026-07-28 (the current revision) with backward compatibility to 2025-11-25, 2025-06-18, 2025-03-26, and 2024-11-05.

10 tools  ·  467 API operations reachable  ·  2,992 tokens of tools/list  ·  OAuth 2.1

Quick start

Remote (recommended)

claude mcp add --transport http nominal https://nominal-mcp.elirapport.workers.dev/mcp

A browser window opens. Paste your own Nominal API key (Nominal app → Settings → API keys). The key is encrypted into an access token scoped to this server and is never stored in plaintext. Every request to Nominal is made with your credential, so the connection can never see more than your account already can.

Local stdio

NOMINAL_API_KEY=<your key> npx nominal-mcp

Per the MCP auth spec, stdio servers read credentials from the environment instead of running an OAuth flow. Nothing is written to disk.

What you can ask for

"Find the last hot-fire run on Engine A and tell me whether chamber pressure ever exceeded 900 psi."

"Compare valve command lag between run 14 and run 15."

"Flag an event on this run at T+4.2s and label it anomaly."

Tools

Plus resources under nominal:// and four workflow prompts (investigate_anomaly, compare_runs, summarize_run, preflight_check).

Three design decisions worth knowing

467 operations, 10 tools. Nominal's API has 467 endpoints across 57 services. Exposing them as tool schemas would cost roughly 163,000 tokens of tools/list before you typed anything. Instead nominal_api_search returns operation descriptors and nominal_api_call executes them, so you pay ~120 tokens per operation you actually look up. tools/list stays fixed at 2,992 tokens and is publicly cacheable.

No tool ever returns a dataset. A single run can be gigabytes of time series. nominal_query_channels returns statistics plus a min/max/mean trace decimated into at most 200 buckets, and a signed handle. Bulk data leaves through a presigned URL that never enters the context window.

Your credential, never ours. There is no service account. The OAuth flow binds your Nominal API key into an encrypted, audience-bound, one-hour access token. Nominal's own authorization is the only enforcement layer — the MCP server never widens access and never implements a parallel permission model.

Documentation

• SPEC.md — the implementation spec: protocol decisions, tool design, auth model, limits, threat model, and what was deliberately left out

• docs/SPEC-original.md — the original design brief, kept for the record; SPEC.md §0 explains where measurement changed it

Development

npm ci
npm run typecheck
npm test              # 115 unit + conformance tests
npm run budget        # fails if tools/list exceeds 3,000 tokens
npm run test:fuzz     # adversarial suite
npm run dev           # wrangler dev

Testing

The fuzzer runs every 20 minutes against the live deployment (.github/workflows/fuzz.yml). Generators cover JSON-RPC structure, the protocol/era matrix, tool arguments, catalog operation ids, auth forgery, and prompt-injection/SSRF payloads. Invariants: never a 5xx, always valid JSON-RPC, never reflects a secret or stack trace, resultType present iff modern, bounded latency and size, and no internal operation ever executes. A failure files an issue with the seed for exact replay.

Deploying your own

npx wrangler kv namespace create OAUTH_KV     # put the id in wrangler.toml
npx wrangler secret put TOKEN_SECRET          # AES-GCM key material
npx wrangler secret put HANDLE_SECRET         # HMAC key for result handles
npx wrangler deploy

For CI deploys set the CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID secrets and a DEPLOY_URL repository variable.

Endpoints

License

MIT