> ## Documentation Index > Fetch the complete documentation index at: https://docs.mcpjam.com/llms.txt > Use this file to discover all available pages before exploring further. # Get the pre-run disclosure for a suite launch plan > What happens to a run's content BEFORE you launch it: which models it calls and where they route, which LLM analyzers/judges can fire and where their evidence goes, capture/retention/region facts, and the subprocessors engaged. Read-only — never launches or gates a run. Keyed by the SAME destination-affecting subset a launch selects (`caseIds`/`environmentId`/`environmentIds`); pass the selectors you would pass to a run so what this discloses is what that run would do. `run_eval_suite` already fetches this itself and returns it on the receipt's `disclosure` field — call this route directly when you need the disclosure BEFORE deciding to launch. A deployment that predates this contract answers 422 `FEATURE_NOT_SUPPORTED` with `details.reason: "contract_unavailable"`, never a partial payload — this is a GUARANTEE only when the deployment's missing-function error reaches this route unredacted. Production Convex can redact that same failure to a generic "Server Error" indistinguishable from a genuine handler crash on a suite the caller CAN see; this route has no independent way to tell the two apart in that one case, so it answers 502 instead of guessing 422 — a caller cannot rely on this code alone to detect an old production deployment, and a 502 does not imply the contract is available either. `projectId` is positional only, for REST consistency with sibling routes — this endpoint authorizes per-suite, not per-project, so any `projectId` returns the same disclosure for a `suiteId` you can reach. ## OpenAPI ````yaml /reference/openapi.json get /projects/{projectId}/eval-suites/{suiteId}/run-disclosure openapi: 3.1.0 info: title: MCPJam API version: 1.0.0-preview description: >- Programmatic access to MCP servers saved in your MCPJam projects — live diagnostics (validate, inspect, export) and operations: call tools, render prompts, run eval suites asynchronously and poll their results, and import OAuth tokens. **The API is in preview**: the surface may change while we finish the design. Error `code` values are stable; error `message` strings are not. Write clients that ignore unknown response fields. contact: name: MCPJam url: https://github.com/MCPJam/inspector/issues servers: - url: https://app.mcpjam.com/api/v1 description: Hosted MCPJam security: - bearerAuth: [] tags: - name: Hosts description: >- Project hosts: named model + capability profiles you run chats and eval suites against. - name: Environments description: >- Project environments: named, live-editable execution bundles (one host, an optional standalone server group, optionally pinned skills and plugin versions) that eval suites and journeys run against. Distinct from Sandbox images, which are Computer base images. Reads require project membership; every write requires project admin. - name: Plugins description: >- Agent Plugins imported into a project — read-only inventory and version detail. - name: Sandbox images description: >- Custom Computer images: a digest-pinned Dockerfile built into an immutable image your project's computers boot from. - name: Server diagnostics description: Connect-level health checks against a saved MCP server. - name: Primitives description: 'The server''s MCP primitives: tools, prompts, and resources.' - name: Export description: Full-server snapshots for diffing and CI. - name: Execution description: 'Run the server''s primitives: call tools, render prompts.' - name: Eval runs description: >- Asynchronous eval suite runs: create with 202, poll status, iterations, and traces. - name: Conformance runs description: >- Ingest MCP spec-conformance results from the SDK/CLI into project-owned history. Distinct from Eval runs (authored LLM cases) and from directory readiness. - name: Server connections description: >- Connect an MCP server URL to a project, authorizing in a browser when the server requires it. - name: OAuth description: 'Bring-your-own OAuth: import externally obtained tokens for a server.' - name: Scenarios description: >- Read-only access to the scenarios published from a project: listing, settings, attached servers, and share links. - name: Catalog description: >- Discover the resources the other routes operate on: your account, projects, servers, eval suites, and chat sessions. - name: Tunnels description: >- Relay tunnels that expose local MCP servers through a public URL, registered as first-class project servers (the `mcpjam cloud tunnel` CLI flow). - name: Agent description: >- Headless agent turns over the public API: send a message history, the server runs one assistant turn with project-scoped workspace tools (eval reads + suite creation) on a pinned hosted model, and returns the reply plus created-resource references. - name: Swarms description: >- Personas, journeys and swarm containers — the authoring half of Swarms — plus the model-backed generation that drafts them. - name: Swarm runs description: >- Launching journeys and reading what they produced. Launching SPENDS — see the per-operation notes. - name: Swarm insights description: >- What a swarm run revealed. The scorecard and findings are deterministic and free; requesting wave insights runs models and draws on your shared daily ledger. - name: User testing description: >- Publishing an environment for real visitors, and controlling who can reach it. Several of these NARROW access and take effect immediately. - name: Directory readiness description: >- Grade a saved server against a publisher's listing requirements: Anthropic's connector directory or OpenAI's plugin directory. Reported as lane status and coverage, never as a numeric score, and excluded from `pooledConformanceScore`. Deterministic grading is free; model-backed experience observations are an explicit opt-in that consumes MCPJam credits and can never decide a verdict. - name: Registry description: >- Search the scraped MCP directories (Claude, ChatGPT, and any future source), list curated/org registry cards, and install them into a project. Install writes a `servers` row and provenance — it does not open a live session. There is no catalog-uninstall route: delete the project server instead. Directory reads require a bearer (including minted guest tokens) but do not materialize a user. Card/connection reads and all writes are authed-non-guest. paths: /projects/{projectId}/eval-suites/{suiteId}/run-disclosure: get: tags: - Eval runs summary: Get the pre-run disclosure for a suite launch plan description: >- What happens to a run's content BEFORE you launch it: which models it calls and where they route, which LLM analyzers/judges can fire and where their evidence goes, capture/retention/region facts, and the subprocessors engaged. Read-only — never launches or gates a run. Keyed by the SAME destination-affecting subset a launch selects (`caseIds`/`environmentId`/`environmentIds`); pass the selectors you would pass to a run so what this discloses is what that run would do. `run_eval_suite` already fetches this itself and returns it on the receipt's `disclosure` field — call this route directly when you need the disclosure BEFORE deciding to launch. A deployment that predates this contract answers 422 `FEATURE_NOT_SUPPORTED` with `details.reason: "contract_unavailable"`, never a partial payload — this is a GUARANTEE only when the deployment's missing-function error reaches this route unredacted. Production Convex can redact that same failure to a generic "Server Error" indistinguishable from a genuine handler crash on a suite the caller CAN see; this route has no independent way to tell the two apart in that one case, so it answers 502 instead of guessing 422 — a caller cannot rely on this code alone to detect an old production deployment, and a 502 does not imply the contract is available either. `projectId` is positional only, for REST consistency with sibling routes — this endpoint authorizes per-suite, not per-project, so any `projectId` returns the same disclosure for a `suiteId` you can reach. operationId: getEvalRunDisclosure parameters: - $ref: '#/components/parameters/projectId' - $ref: '#/components/parameters/suiteId' - name: caseIds in: query required: false description: >- Comma-separated test case IDs to narrow the disclosure to, instead of the whole suite. schema: type: string - name: environmentId in: query required: false description: >- One attached environment to disclose for. Mutually exclusive with `environmentIds` and `host`. schema: type: string - name: environmentIds in: query required: false description: >- Comma-separated attached environment IDs to disclose for, mirroring a multi-target launch. Mutually exclusive with `environmentId` and `host`. schema: type: string - name: host in: query required: false description: >- One attached host to disclose for, mirroring a host-targeted launch — the engine and sandbox facts come from that host's own config. Mutually exclusive with `environmentId`/`environmentIds`: a launch plan resolves on exactly one axis. schema: type: string responses: '200': description: The pre-run disclosure. content: application/json: schema: $ref: '#/components/schemas/EvalRunDisclosure' '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '422': description: >- This deployment predates the pre-run disclosure contract (`details.reason: "contract_unavailable"`). Guaranteed only when the missing-function failure reaches this route unredacted; an ambiguous production-redacted failure on a suite the caller can see surfaces as 502 instead — see the operation description. content: application/json: schema: $ref: '#/components/schemas/Error' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' '502': $ref: '#/components/responses/ServerUnreachable' components: parameters: projectId: name: projectId in: path required: true description: ID of the hosted project that contains the server. schema: type: string suiteId: name: suiteId in: path required: true description: Eval suite ID, as returned by `POST /eval-runs`. schema: type: string schemas: EvalRunDisclosure: type: object required: - contractVersion - computedAt - digest - analysis - capture - retention - region - subprocessors description: >- What happens to a run's content: computed once by the backend and projected identically by the pre-run dialog, the CLI, MCP tools, and the `eval.run.launched` audit row. `execution` is present ONLY when a launch plan resolved; `executionAbsence` exactly when it is absent, naming WHICH of two reasons (`ingested-run` — MCPJam did not execute this; `plan-unresolved` — a run that WILL execute and WILL call models, just not derivable yet). `analysis` is ALWAYS present, even without `execution`: stored evidence still reaches the judges. properties: contractVersion: type: integer computedAt: type: integer description: >- Epoch ms. Excluded from `digest`, so identical facts digest identically regardless of when they were computed. digest: type: string description: >- SHA-256 hex over the canonical JSON of the facts (excluding `digest`/`computedAt` and each managed rail's `observedAt`). execution: type: object description: Present exactly when a launch plan resolved. properties: engine: type: string description: '`emulated`, `mixed`, or `harness:`.' engines: type: array items: type: string description: >- Present only when `engine` is `mixed` — the per-plan detail it summarizes. sandbox: type: object properties: engaged: type: boolean vendor: type: string because: type: string locus: type: object description: >- Whether this run executes MCPJam-hosted or on the caller's own machine — a fact only the executing process (the inspector) can answer, composed onto the backend's contract. properties: known: type: boolean hosted: type: boolean reason: type: string models: type: array items: type: object description: >- One disclosed model: its id, provider classification, tenant egress (`mcpjam-hosted` | `byok-cloud` | `byok-local` | `unknown`), and the rail it travels. modelsUnresolved: type: object description: Present when the plan resolved but its models did not. properties: reason: type: string executionAbsence: type: object description: Present exactly when `execution` is absent. required: - kind - reason properties: kind: type: string enum: - ingested-run - plan-unresolved reason: type: string analysis: type: array items: type: object description: >- One LLM analyzer/judge touchpoint: its model, rail, evidence sent, and whether it fires for this run. capture: type: object description: >- Capture level, reporting mode, and redaction facts (fixed for this contract version). retention: type: object description: >- Plan retention policy, whether it is actually enforced, and what that means today (`kept-indefinitely` vs `swept-after-policy-days`). region: type: object description: >- `{ stated: false, reason }` unless a BYOK base URL carries a derivable region token. subprocessors: type: array items: type: object description: >- One vendor this run may reach, with whether it is actually engaged for this plan and why. Error: type: object required: - code - message properties: code: type: string description: >- Stable, machine-readable error code. New codes may be added over time; treat unknown codes as non-retryable failures unless the HTTP status says otherwise. enum: - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - CONFLICT - VALIDATION_ERROR - RATE_LIMITED - FEATURE_NOT_SUPPORTED - SERVER_UNREACHABLE - TIMEOUT - OAUTH_REQUIRED - INTERNAL_ERROR message: type: string description: >- Human-readable description. May change between releases — don't match on it. details: type: object description: Optional, unstructured context bag. additionalProperties: true responses: ValidationError: description: Malformed body or parameters. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: VALIDATION_ERROR message: Invalid JSON body Unauthorized: description: >- Missing, invalid, revoked, or orphaned key (`UNAUTHORIZED`) — or the **target MCP server** needs an OAuth grant (`OAUTH_REQUIRED`), which is a property of the server, not your key. content: application/json: schema: $ref: '#/components/schemas/Error' examples: badKey: summary: Invalid or revoked key value: code: UNAUTHORIZED message: Invalid API key oauthRequired: summary: Target server needs an OAuth grant value: code: OAUTH_REQUIRED message: Server requires OAuth authorization NotFound: description: Unknown project, server, or resource. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: NOT_FOUND message: Server not found RateLimited: description: >- Per-key rate limit exceeded (60 requests/minute sustained, bursts up to 10). Honor `Retry-After` and back off with jitter. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' example: code: RATE_LIMITED message: API key rate limit exceeded. Slow down and retry. InternalError: description: Something failed on MCPJam's side. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: INTERNAL_ERROR message: Unexpected internal error ServerUnreachable: description: Could not connect to the target MCP server. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: SERVER_UNREACHABLE message: Failed to connect to server securitySchemes: bearerAuth: type: http scheme: bearer description: >- MCPJam API key (`sk_…`). Create one at [Settings → API keys](https://app.mcpjam.com/settings/api-keys). Guest sessions cannot use the API, and API keys cannot manage other API keys. ````