> ## 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.

# Build findings for an eval run

> Builds (or with `force`, rebuilds) a settled run's findings from its recorded evidence: the findings an analysis explains. Deterministic, with no model call, no credits and no quota.

`202`: scheduled, not done. Poll the run detail's `insights.unifiedFindings.job` until its `status` is `completed`. On a run that has never been analyzed, a finished build starts the analysis automatically; otherwise request it with `POST /projects/{projectId}/eval-runs/{runId}/insights`.

`409` while a build is running, when findings exist and `force` is absent, and while the run is still running or grading.



## OpenAPI

````yaml /reference/openapi.json post /projects/{projectId}/eval-runs/{runId}/findings/build
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: Clients
    description: >-
      Clients: the named, reusable configurations that define how MCPJam
      connects to and talks to your MCP servers. The original `/hosts` paths
      remain as deprecated, ID-only compatibility aliases with their original
      DTOs and their original (tokenless) write contracts; every alias response
      carries `Deprecation: true`. New integrations should use `/clients`.
  - name: Environments
    description: >-
      Project environments: named, live-editable execution bundles (one host and
      an optional standalone server group) that eval suites and goals run
      against. Reads require project membership; archiving requires project
      admin.
  - 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: Server accounts
    description: >-
      The accounts a saved server signs in with, addressed by id or by name.
      Tokens are write-only: an upload takes them and no route returns one.
  - name: OAuth
    description: 'Bring-your-own OAuth: import externally obtained tokens for a server.'
  - name: Studies
    description: >-
      Publish a project environment as a **study** for people outside the
      project to talk to, read what they did, and control who can reach it.
      Several of these NARROW access and take effect immediately.


      The pre-rename paths (`/projects/{projectId}/scenarios`,
      `/projects/{projectId}/scenarios/{scenarioId}`,
      `/projects/{projectId}/environments/{environmentId}/scenario` and
      `/projects/{projectId}/user-testing/scenarios/{scenarioId}/…`) keep
      working and are deliberately not documented here. They return their
      original bodies, which spell the owning id `scenarioId` and whose detail
      read carries no execution settings, and every response answers with
      `Deprecation: true` and a `Link` header naming its successor. They are
      removed at general availability; a new integration should use the paths on
      this page.
  - 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: 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 whose model cost is on
      MCPJam (no credits are consumed) and they can never decide a verdict.
  - name: Feedback
    description: >-
      Feedback about MCPJam itself (bugs, missing capabilities, confusing
      behavior), sent to the MCPJam team and kept for 180 days. The
      `send_feedback` MCP tool calls the same endpoint.
paths:
  /projects/{projectId}/eval-runs/{runId}/findings/build:
    parameters:
      - $ref: '#/components/parameters/evalVocabularyHeader'
      - $ref: '#/components/parameters/projectId'
      - $ref: '#/components/parameters/runId'
    post:
      tags:
        - Evals
      summary: Build findings for an eval run
      description: >-
        Builds (or with `force`, rebuilds) a settled run's findings from its
        recorded evidence: the findings an analysis explains. Deterministic,
        with no model call, no credits and no quota.


        `202`: scheduled, not done. Poll the run detail's
        `insights.unifiedFindings.job` until its `status` is `completed`. On a
        run that has never been analyzed, a finished build starts the analysis
        automatically; otherwise request it with `POST
        /projects/{projectId}/eval-runs/{runId}/insights`.


        `409` while a build is running, when findings exist and `force` is
        absent, and while the run is still running or grading.
      operationId: buildEvalRunFindings
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EvalRunFindingsBuildRequest'
      responses:
        '202':
          description: Scheduled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvalRunFindingsBuildRequested'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'
        '502':
          $ref: '#/components/responses/ServerUnreachable'
components:
  parameters:
    evalVocabularyHeader:
      name: x-mcpjam-eval-vocabulary
      in: header
      required: false
      description: >-
        Which vocabulary this request and its response speak. Absent means `1`,
        which is byte-for-byte today's contract: the same request fields, the
        same refusals, the same response projection. `2` is the canonical
        vocabulary. Any other value is a `400` with `code: "VALIDATION_ERROR"`.


        Today it decides one thing: the spelling of an evaluator's policy
        `role`. Vocabulary 1 accepts and returns `gating`; vocabulary 2 accepts
        both spellings and returns the canonical `required`. Sending `required`
        without the header is a `400`, deliberately: vocabulary 1 is not widened
        to meet vocabulary 2 half way, because a boundary that accepts a
        spelling it does not announce is one two implementations can disagree
        about.


        A response that varies by vocabulary sends `Vary:
        x-mcpjam-eval-vocabulary`.
      schema:
        type: string
        enum:
          - '1'
          - '2'
      example: '2'
    projectId:
      name: projectId
      in: path
      required: true
      description: ID of the hosted project that contains the server.
      schema:
        type: string
    runId:
      name: runId
      in: path
      required: true
      description: Eval run ID, as returned by `POST /eval-runs`.
      schema:
        type: string
  schemas:
    EvalRunFindingsBuildRequest:
      type: object
      additionalProperties: false
      properties:
        force:
          type: boolean
          description: Rebuild over findings that already exist. Must be a real boolean.
    EvalRunFindingsBuildRequested:
      type: object
      required:
        - runId
        - projectId
        - status
      properties:
        runId:
          type: string
        projectId:
          type: string
        status:
          type: string
          enum:
            - pending
    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
            - AUTH_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
    Forbidden:
      description: Key is valid but not allowed to do this.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: FORBIDDEN
            message: You do not have access to this project
    NotFound:
      description: Unknown project, server, or resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: NOT_FOUND
            message: Server not found
    Conflict:
      description: >-
        The resource is not in a state that accepts this write: a stale
        `expectedRevision`, a duplicate name, or an environment that cannot
        currently be launched. The request was well-formed; re-read the resource
        and retry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: CONFLICT
            message: >-
              Environment changed since you loaded it (expected revision 3,
              current 5). Reload 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.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.