> ## 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. # Run one headless agent turn > Runs ONE assistant turn over the supplied message history and responds synchronously with the final assistant text, the operations it invoked, and references to any resources it created (currently eval suites). The caller owns conversation state: resend the full history each turn. The model is pinned server-side (hosted catalog) and billed to the project. Tools available to the turn are read operations plus atomic `create_eval_suite`; run/cancel and generation operations are deliberately excluded — starting a run stays an explicit caller action via `POST /eval-runs`. Every tool invocation is hard-clamped to the path `projectId`. Turns are capped at 4 concurrent per organization (`429 RATE_LIMITED`; enforced per server instance) and ~90s wall clock (`504 TIMEOUT`). Guest callers are denied. Requires a hosted MCPJam deployment (`422 FEATURE_NOT_SUPPORTED` otherwise). When a turn fails or times out AFTER a create operation already persisted a resource, the error body's `details.createdResources` carries the created references — check it before retrying, or a retry will create duplicates. **Retry policy:** this operation is NOT idempotent — a turn may persist resources (eval suites) even when the response is lost, and there is no idempotency key yet. Do not blind-retry: deduplicate on your own trigger identity (e.g. the Slack event id) and, when a retry is unavoidable, first list suites to check whether the previous attempt already created one. ## OpenAPI ````yaml /reference/openapi.json post /projects/{projectId}/agent 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: 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: OAuth description: 'Bring-your-own OAuth: import externally obtained tokens for a server.' - name: Chatboxes description: >- Read-only access to the chatboxes 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 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. paths: /projects/{projectId}/agent: post: tags: - Agent summary: Run one headless agent turn description: >- Runs ONE assistant turn over the supplied message history and responds synchronously with the final assistant text, the operations it invoked, and references to any resources it created (currently eval suites). The caller owns conversation state: resend the full history each turn. The model is pinned server-side (hosted catalog) and billed to the project. Tools available to the turn are read operations plus atomic `create_eval_suite`; run/cancel and generation operations are deliberately excluded — starting a run stays an explicit caller action via `POST /eval-runs`. Every tool invocation is hard-clamped to the path `projectId`. Turns are capped at 4 concurrent per organization (`429 RATE_LIMITED`; enforced per server instance) and ~90s wall clock (`504 TIMEOUT`). Guest callers are denied. Requires a hosted MCPJam deployment (`422 FEATURE_NOT_SUPPORTED` otherwise). When a turn fails or times out AFTER a create operation already persisted a resource, the error body's `details.createdResources` carries the created references — check it before retrying, or a retry will create duplicates. **Retry policy:** this operation is NOT idempotent — a turn may persist resources (eval suites) even when the response is lost, and there is no idempotency key yet. Do not blind-retry: deduplicate on your own trigger identity (e.g. the Slack event id) and, when a retry is unavoidable, first list suites to check whether the previous attempt already created one. operationId: runAgentTurn parameters: - $ref: '#/components/parameters/projectId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AgentTurnRequest' example: messages: - role: user content: >- Create an eval suite for my weather server with one case that checks get_forecast is called for "forecast for Paris". responses: '200': description: The completed turn. content: application/json: schema: $ref: '#/components/schemas/AgentTurnResponse' example: reply: >- Created the suite "weather smoke" with 1 case. It is ready to run. toolCalls: - operation: list_project_servers - operation: create_eval_suite createdResources: - type: eval_suite id: ts_abc123 name: weather smoke url: https://app.mcpjam.com/evals/suite/ts_abc123 usage: inputTokens: 2450 outputTokens: 312 '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/FeatureNotSupported' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' '504': $ref: '#/components/responses/Timeout' components: parameters: projectId: name: projectId in: path required: true description: ID of the hosted project that contains the server. schema: type: string schemas: AgentTurnRequest: type: object required: - messages properties: messages: type: array minItems: 1 maxItems: 50 description: >- The conversation so far, oldest first. The caller owns state and resends the full history each turn. Each message content is capped at 8,000 characters AND 8,192 UTF-8 bytes; the whole history is additionally capped at 98,304 UTF-8 bytes (96 KB). items: type: object required: - role - content properties: role: type: string enum: - user - assistant content: type: string minLength: 1 maxLength: 8000 description: Plain text. Max 8,000 characters and 8,192 UTF-8 bytes. AgentTurnResponse: type: object required: - reply - toolCalls - createdResources - usage properties: reply: type: string description: The assistant's final text for this turn. toolCalls: type: array items: type: object required: - operation properties: operation: type: string description: Platform operation name invoked during the turn. createdResources: type: array description: Resources the turn created, with app deep links. items: type: object required: - type - id - url properties: type: type: string enum: - eval_suite id: type: string name: type: string url: type: string format: uri usage: type: object required: - inputTokens - outputTokens properties: inputTokens: type: integer outputTokens: type: integer 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 FeatureNotSupported: description: The target server doesn't support this MCP capability. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: FEATURE_NOT_SUPPORTED message: Server does not support resources 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 Timeout: description: The target MCP server connected but didn't respond in time. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: TIMEOUT message: Request to server timed out 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. ````