MCPJam API

• Discover your resources — list your projects, their servers, eval suites, and chat sessions, so every ID the other routes need is self-serve
• Validate a server — connect, initialize, and capture a capability snapshot
• Run the doctor — the probe → connect → initialize → capabilities workflow
• Check OAuth requirements — does this server need an OAuth grant?
• List tools, prompts, and resources — the server’s MCP primitives
• Call a tool / render a prompt — execute primitives and get the MCP result back verbatim
• Read a resource by URI
• Export a full snapshot — tools, resources, and prompts as one JSON document
• Manage a project’s hosts — list, read, create (from a built-in template like claude/chatgpt/cursor, or from a full host config), rename, and delete the named model + capability profiles you run chats and eval suites against
• Manage a project’s environments — list, read, create, edit, archive, and restore the named execution bundles (host + optional server group + optional pinned skills and plugin versions) that eval suites and journeys run against, and preview what one resolves to before launching it
• List a project’s scenarios — name, access mode, attached servers, and share link — and read one scenario’s settings: model, system prompt, tool-approval policy, and resolved servers
• Author eval suites — create a runnable suite (name, default model, servers, test cases) synchronously and get a suiteId back; no run is started and no credits are spent
• Run eval suites asynchronously — create a run from a saved suite, get a 202 + runId immediately, then poll status, per-iteration results (tool calls, token usage, latency), and full traces. Runs appear live in the hosted UI, tagged source: "api"
• Import OAuth tokens — complete OAuth yourself (e.g. the SDK’s runOAuthLogin) and push the tokens; subsequent calls inject and refresh them server-side
• Run a headless agent turn — send a message history, get back the assistant reply, the platform operations it invoked, references to any resources it created (eval suites), and token usage; the model is pinned server-side and billed to the project

​

Base URL

https://app.mcpjam.com/api/v1

​

Authentication

curl -X POST \
  "https://app.mcpjam.com/api/v1/projects/$PROJECT_ID/servers/$SERVER_ID/tools" \
  -H "Authorization: Bearer $MCPJAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

​

Creating a key

1. Open Settings → API keys in the hosted app (the card at the top of this page takes you there directly).
2. Click Create API key, name it, and pick the organization it will act in.
3. Copy the key (sk_…) immediately — it is shown exactly once and never stored by MCPJam in retrievable form.

​

Scope

​

Keep keys secret

• Load it from an environment variable or secret manager — never commit it to source control or ship it in client-side code.
• Scope keys narrowly: one key per integration, named so you can tell them apart.
• Rotate by creating a replacement key, switching traffic, then revoking the old one.
• If a key leaks, revoke it immediately in Settings → API keys.

​

Conventions

​

Errors

​

Rate limits

HTTP/1.1 429 Too Many Requests
Retry-After: 7

{ "code": "RATE_LIMITED", "message": "API key rate limit exceeded. Slow down and retry." }

​

Endpoints

• Always send Idempotency-Key on a launch. It spends model credits, so a retry of a dropped response must not run the journey twice. Replaying a key returns the original run with deduped: true and starts no second runner — and consumes no quota. Omitting the header is read as a request that declined to identify itself, and gets a fresh run every time.
• Check canceled before reporting a failure. A stopped run carries status: "failed", because cancellation is recorded as a marker rather than a status of its own. stale: true is the third case: the runner went silent and the watchdog settled the run.
• targetId, not hostId, identifies a target. Two environments can resolve to the same host with different servers, so a run can hold two targets that share a hostId.

• Divide by sessionsGraded, never by the session total. Three failures out of four graded sessions, in a run that attempted forty, is 75% — not 7.5%.
• failedGradingCount is not failCount. A crashed judge is not a regression, and folding the two together makes one look like the other.

​

Run evals from the API

# 1. Create (responds 202 immediately; -f + jq -e fail fast on errors)
RUN_ID=$(curl -fsS -X POST \
  "https://app.mcpjam.com/api/v1/projects/$PROJECT_ID/eval-runs" \
  -H "Authorization: Bearer $MCPJAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "suiteName": "smoke",
    "serverIds": ["'$SERVER_ID'"],
    "tests": [{
      "title": "echo works",
      "runs": 1,
      "model": "anthropic/claude-haiku-4.5",
      "provider": "anthropic",
      "steps": [
        { "id": "s1", "kind": "prompt", "prompt": "Use the echo tool to say hi" },
        {
          "id": "s2",
          "kind": "assert",
          "assertion": {
            "type": "toolCalledWith",
            "toolName": "echo",
            "args": { "args": { "text": "hi" } }
          }
        }
      ]
    }]
  }' | jq -er .runId)

# 2. Poll until status is completed | failed | cancelled
curl -s "https://app.mcpjam.com/api/v1/projects/$PROJECT_ID/eval-runs/$RUN_ID" \
  -H "Authorization: Bearer $MCPJAM_API_KEY"

# 3. Inspect per-iteration tool calls, token usage, latency
curl -s "https://app.mcpjam.com/api/v1/projects/$PROJECT_ID/eval-runs/$RUN_ID/iterations" \
  -H "Authorization: Bearer $MCPJAM_API_KEY"

​

Running against a project environment

• no attached environments → the run uses the saved server selection, as before;
• exactly one attached → that environment is used automatically. The 202 response’s environment field says so;
• several attached → 400 with details.reason: "ENVIRONMENT_REQUIRED", naming the candidates.

​

Not in the API yet

• Creating or revoking API keys (UI-only by design — see Authentication)
• Chat and conformance suites
• Browser-based OAuth flows initiated by the API (use oauth/import-tokens after completing OAuth yourself)

​

Versioning & stability

• The API is path-versioned (/api/v1). When it reaches general availability, breaking changes will require a new version path.
• During the preview, breaking changes to v1 may still happen; we’ll note them in the changelog.
• Additive changes — new endpoints, new optional request fields, new response fields, new error codes — are considered non-breaking and can ship at any time. Write clients that ignore unknown fields.
• Error codes are stable identifiers; error messages are not.