> ## Documentation Index > Fetch the complete documentation index at: https://docs.erstan.com/llms.txt > Use this file to discover all available pages before exploring further. # MCP endpoint > Stateless streamable-HTTP MCP endpoint (JSON-RPC 2.0). Supports `initialize`, `tools/list`, and `tools/call`. `tools/list` returns only the tools allowed by the connected-app OAuth grant or API-key scopes; `tools/call` re-checks that authorization, the connection owner's current permissions, and applicable resource boundaries on every call. `publish_agent` validates and publishes only the exact current manageable revision; authoring never archives or deletes an agent. `test_agent` can run the guarded current draft in Builder Preview. `update_agent`, `validate_agent`, and `publish_agent` require both `agents:read` and `agents:write`; `create_agent` requires `agents:write`. `run_agent` accepts optional top-level attachments with `name`, `type`, and either `base64` content or an existing `storageKey`. `comment_on_task` accepts optional inline base64 attachments under the Manage work permission; `read_task` returns their `teamFileId` and comment `activityId` for later retrieval when View files is also granted. The Task surface also supports complete property/hierarchy updates, structured upload/Team-file/document/URL attachments (Inbox excluded), comment edit/delete, participants, reactions, and lifecycle operations. `list_task_options` returns scoped selectable teams, projects, eligible Agents, members, labels, and non-cyclic parent Tasks under View work. `read_task` returns parent/subtask, participant, attachment, thread, execution, and approval references. Task-linked run tools authorize the visible Task and exact Task-to-execution-to-thread relationship, so they use View work/Manage work rather than requiring an additional View runs or Run agents grant. General run tools remain same-credential scoped. GET and DELETE return `405` — there are no SSE sessions in v1. See the [Connect a Coding Agent](/developers/connect-coding-agent) guide for the tool table and client configuration. ## OpenAPI ````yaml /openapi/public-api.yaml post /v1/mcp openapi: 3.1.0 info: title: Erstan Public Agent API version: 1.2.0 description: >- Start published Erstan agents from external systems and poll for results. API keys carry scopes (`agents:list`, `agents:read`, `agents:write`, `agents:run`, `runs:read`, `tasks:execute`, `documents:read`, `documents:write`, `files:read`, `files:write`). Agent access follows the key creator's current workspace and team permissions. Project and team allowlists (`allowedProjectIds`, `allowedTeamIds`) further restrict task and document and file access. Agent draft authoring and task/document/file tools are exposed through the MCP server at `/v1/mcp` rather than REST routes. servers: - url: https://api.erstan.com description: Public endpoint security: - PublicApiKey: [] tags: - name: Agents description: >- Discover and run published agents available to the key creator under their current permissions. - name: Runs description: Read run status and results. - name: MCP description: >- Model Context Protocol server for external clients. Agent Builder tools use `agents:read`, `agents:write`, or both, plus the key creator's live Erstan permissions. Task and content tools also apply project/team allowlists. paths: /v1/mcp: post: tags: - MCP summary: MCP endpoint description: >- Stateless streamable-HTTP MCP endpoint (JSON-RPC 2.0). Supports `initialize`, `tools/list`, and `tools/call`. `tools/list` returns only the tools allowed by the connected-app OAuth grant or API-key scopes; `tools/call` re-checks that authorization, the connection owner's current permissions, and applicable resource boundaries on every call. `publish_agent` validates and publishes only the exact current manageable revision; authoring never archives or deletes an agent. `test_agent` can run the guarded current draft in Builder Preview. `update_agent`, `validate_agent`, and `publish_agent` require both `agents:read` and `agents:write`; `create_agent` requires `agents:write`. `run_agent` accepts optional top-level attachments with `name`, `type`, and either `base64` content or an existing `storageKey`. `comment_on_task` accepts optional inline base64 attachments under the Manage work permission; `read_task` returns their `teamFileId` and comment `activityId` for later retrieval when View files is also granted. The Task surface also supports complete property/hierarchy updates, structured upload/Team-file/document/URL attachments (Inbox excluded), comment edit/delete, participants, reactions, and lifecycle operations. `list_task_options` returns scoped selectable teams, projects, eligible Agents, members, labels, and non-cyclic parent Tasks under View work. `read_task` returns parent/subtask, participant, attachment, thread, execution, and approval references. Task-linked run tools authorize the visible Task and exact Task-to-execution-to-thread relationship, so they use View work/Manage work rather than requiring an additional View runs or Run agents grant. General run tools remain same-credential scoped. GET and DELETE return `405` — there are no SSE sessions in v1. See the [Connect a Coding Agent](/developers/connect-coding-agent) guide for the tool table and client configuration. operationId: postMcp requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/JsonRpcRequest' examples: toolsList: summary: List tools available to this key value: jsonrpc: '2.0' id: 1 method: tools/list getNextTask: summary: Fetch the next eligible task value: jsonrpc: '2.0' id: 2 method: tools/call params: name: get_next_task arguments: {} commentOnTaskWithAttachment: summary: Add a Task comment with a base64-encoded file attachment value: jsonrpc: '2.0' id: 3 method: tools/call params: name: comment_on_task arguments: taskId: task_abc123 body: Review the attached evidence. attachments: - name: evidence.txt type: text/plain base64: aW52b2ljZSA0Mg== runAgentWithAttachment: summary: Start an Agent with a base64-encoded file attachment value: jsonrpc: '2.0' id: 3 method: tools/call params: name: run_agent arguments: agentId: agent_abc123 laneId: start_chat input: message: Process the attached supplier order. attachments: - name: supplier-order.xlsx type: >- application/vnd.openxmlformats-officedocument.spreadsheetml.sheet base64: UEsDBBQAAAAI... idempotencyKey: supplier-order-2026-08-01 decideTaskLinkedApproval: summary: >- Decide the current approval through a visible Task relationship value: jsonrpc: '2.0' id: 4 method: tools/call params: name: decide_task_run_approval arguments: taskId: task_abc123 runId: run_abc123 interactionId: approval:approval_abc123 action: approve createAgentDraft: summary: Create an Agent Builder draft value: jsonrpc: '2.0' id: 3 method: tools/call params: name: create_agent arguments: teamId: team_abc123 name: Request summarizer behaviorType: pipeline nodes: - id: start_form type: start position: x: 0 'y': 0 data: label: External request triggerType: input_form triggerConfig: inputForm: title: Submit a request fields: - id: request key: request label: Request type: textarea required: true - id: reply type: agent position: x: 280 'y': 0 data: label: Summarize request instructions: Summarize {{input.request}} for a human reviewer. toolPolicy: none edges: - id: start-to-reply source: start_form target: reply updateNeverPublishedAgentDraft: summary: Update metadata on a never-published draft value: jsonrpc: '2.0' id: 4 method: tools/call params: name: update_agent arguments: agentId: agent_abc123 revision: rev_MjAyNi0wNy0xMlQwMDowMDowMC4wMDBa version: 1 description: Summarize and prioritize submitted requests. publishValidatedAgentDraft: summary: Publish the exact validated agent revision value: jsonrpc: '2.0' id: 5 method: tools/call params: name: publish_agent arguments: agentId: agent_abc123 revision: rev_MjAyNi0wNy0xMlQwMDowMDowMC4wMDBa version: 1 responses: '200': description: >- JSON-RPC response. Tool errors are returned inside the JSON-RPC envelope, not as HTTP errors. content: application/json: schema: $ref: '#/components/schemas/JsonRpcResponse' '401': $ref: '#/components/responses/Unauthorized' '429': description: Per-connection rate limit exceeded (default 60 calls per minute). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - ConnectedAppOAuth: [] - PublicApiKey: [] components: schemas: JsonRpcRequest: type: object additionalProperties: false required: - jsonrpc - method description: JSON-RPC 2.0 request accepted by the MCP endpoint. properties: jsonrpc: type: string const: '2.0' id: type: - string - number - 'null' description: Omitted for notifications. method: type: string description: MCP method, such as `initialize`, `tools/list`, or `tools/call`. params: type: object additionalProperties: true description: For `tools/call`, includes `name` (tool name) and `arguments`. JsonRpcResponse: type: object description: JSON-RPC 2.0 response envelope returned by the MCP endpoint. required: - jsonrpc properties: jsonrpc: type: string const: '2.0' id: type: - string - number - 'null' result: type: object additionalProperties: true description: >- Present on success. Tool results are `content` arrays of `{type:'text', text}` items containing stable JSON payloads. error: type: object additionalProperties: true description: >- Present on failure, including scope, permission, allowlist (`access_not_configured`), validation, and rate-limit errors. ErrorResponse: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string message: type: string details: type: array items: $ref: '#/components/schemas/ErrorDetail' requestId: type: string ErrorDetail: type: object required: - code - message properties: field: type: string code: type: string message: type: string responses: Unauthorized: description: Missing, invalid, expired, revoked, or inactive API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: PublicApiKey: type: http scheme: bearer bearerFormat: ers_live API key description: >- Workspace API key created in Erstan Settings. Keys carry scopes (`agents:list`, `agents:read`, `agents:write`, `agents:run`, `runs:read`, `tasks:execute`, `documents:read`, `documents:write`, `files:read`, `files:write`). Agent access follows the key creator's current workspace, team, and agent permissions. Agent draft creation requires `agents:write`; update, validation, and publishing require both `agents:read` and `agents:write`; draft testing also requires `agents:run`. Keys with `tasks:execute` must include at least one allowed project or team (`allowedProjectIds` / `allowedTeamIds`); keys with document or file scopes must include at least one allowed team. Empty allowlists mean no access — the API fails closed. ConnectedAppOAuth: type: oauth2 description: >- Recommended authorization for Claude, Codex, and other interactive MCP hosts. Install the official Erstan plugin, complete browser consent, and manage the resulting grant in Settings > Connected apps. flows: authorizationCode: authorizationUrl: https://api.erstan.com/oauth/authorize tokenUrl: https://api.erstan.com/oauth/token scopes: agents.read: View agents, Skills, tools, and builder guidance. agents.author: Build and validate agent and Skill drafts. agents.run: Run and test agents, reply to runs, and decide approvals. agents.publish: Publish agents and Skills. runs.read: View run status and traces. work.read: >- View tasks, projects, selectable Task relationships, and Task-linked run status or traces. work.write: >- Create and update tasks, comments, attachments, participants, reactions, lifecycle state, and Task-linked run interactions or approvals. documents.read: View and search documents and folders. documents.write: Create and edit documents. files.read: View and read files. files.write: Create and update files. ````