MCP API Reference
Detailed specification of the MCP (Model Context Protocol) endpoint provided by the AGENTIC STAR Marketplace edition. MCP-capable AI clients (such as Claude Code and Codex) connect to AGENTIC STAR and, via tool calls, send requests to registered Agents, retrieve files, work with projects, and run published workflows.
MCP is available only in environments where an administrator has opened the MCP inbound endpoint. Otherwise the endpoint returns 404 Not Found. For how to open it, see the Helm Values Reference in the Build section.
For client configuration and how to connect, see AI Client Connection Guide (MCP). For a connection-method overview, see the Connection Methods Guide.
Base URL
All requests are sent to the following base URL. Replace <your-domain> with the domain of your environment.
https://<your-domain>Endpoint
| Method | Endpoint | Description |
|---|---|---|
POST | /api/v1/mcp | MCP JSON-RPC endpoint (Streamable HTTP, Stateless mode) |
Protocol: JSON-RPC 2.0 over Streamable HTTP
Mode: Stateless (no sessions)
Authentication
All requests must include the Authorization: Bearer <access_token> header. The following two kinds of tokens can be used. The Marketplace edition applies no scope restrictions.
| Token | How to get it | Available tools |
|---|---|---|
| A user token of an application (sign-in from an external tool) | Sign in with the AI client (AI Client Connection Guide (MCP)) | All tool sets. As with REST, what you can do with projects depends on how the user participates in each project |
| A system integration (service account) token | Client Credentials flow (Authentication Guide) | The tools of the chat set, four operations of the project set (list of project_read, get of run_read, start_run and fire_trigger of project_run), and the tools of the published set |
- Sign-in from an external tool is available only in environments where an administrator has opened its entrance (API Setup Guide)
- A user token obtained in any other way (such as the token used when signing in to the Main Screen) gets
404 Not Found - A missing or invalid token gets
401 Unauthorized - In environments where both the MCP inbound endpoint and the entrance for sign-in from an external tool are open, the AI client finds the authorization server to sign in to by itself (Protected Resource Metadata in MCP Specification — Authorization). There is no automatic client registration (dynamic client registration). Set the ID of the client created in the console of the authorization server in the AI client (API Setup Guide)
Tool Sets (?toolsets=)
Select the tool sets with the toolsets query of the endpoint URL.
| Query | Available tools |
|---|---|
None, or ?toolsets=chat | The chat set (5 tools) |
?toolsets=project | The project set (14 tools) |
?toolsets=published | The published set (one tool per published project, and get_project_run) |
?toolsets=chat,project,published | All three sets |
Example: https://<your-domain>/api/v1/mcp?toolsets=chat,project
- Unknown names are ignored and reported at the beginning of
instructionsin the response toinitialize(orserver/discover). If no known name is given, only the chat set is used - The tools returned by
tools/listdepend only on the tool sets selected, not on the kind of token (user or system integration). When a system integration token calls an operation it cannot use, a tool error (isError: true) returnsforbidden
Supported Protocol Versions
The endpoint accepts the following MCP protocol revisions. Clients of both the new and the earlier style can connect.
| Revision | Connection style |
|---|---|
2026-07-28 | The protocol version and client capabilities are sent on every request (initialize is not used) |
2025-11-25 | The version is negotiated with initialize |
2025-06-18 | The version is negotiated with initialize |
2025-03-26 | The version is negotiated with initialize |
2024-11-05 | The version is negotiated with initialize |
2024-10-07 | The version is negotiated with initialize |
Provided Tools
The tools available via tools/call are as follows for each tool set.
Chat Set
| Tool | Description |
|---|---|
execute_chat | Send a task to a registered Agent and get the result |
get_file_content | Get a deliverable file |
cancel_chat | Cancel a running task |
list_agents | Get the list of registered Agents that execute_chat can run |
list_conversation_messages | Read the messages of your conversation |
The arguments and responses of each tool are in the tool descriptions and input schemas returned by tools/list. Errors are returned as tool errors (isError: true), with the kind of error in structuredContent.errorCode.
The list of list_agents contains all active registered Agents. The description of each Agent (description) is the "Description shown in list_agents" in the "External access (MCP / A2A)" section of the Agent in the admin screen. When it is not written, it is the Agent's description in the admin screen, or the display name if that is not written either.
The responses of execute_chat and list_conversation_messages hold the results of the tools the agent used, as stored. These include responses from external MCP servers that an administrator allowed to connect. AGENTIC STAR does not inspect their content.
Project Set
The 14 tools that work with projects, runs, executions, work items, the queue, and connectors. The tools are grouped by resource, and the argument method selects the operation (tools with a single operation do not use method). Every operation works with the same arguments, response, and error codes as the same endpoint in the User API Reference (Projects) (for the exceptions, see "Arguments" and "Response" below the table). Checks such as project membership and ownership are also the same as REST.
| Tool | Purpose | method | REST equivalent | System integration |
|---|---|---|---|---|
project_read | Read projects | list | GET /v1/projects | ✅ |
list_shared | GET /v1/projects/shared | |||
get | GET /v1/projects/{projectId} | |||
get_control | GET /v1/projects/{projectId}/control | |||
list_organizations | GET /v1/projects/organizations | |||
project_status_read | Read the queue, KPIs, and records (audit trail) | list_my_queue | GET /v1/queue | |
list_queue | GET /v1/projects/{projectId}/queue | |||
get_kpi | GET /v1/projects/{projectId}/kpi | |||
list_audit_events | GET /v1/projects/{projectId}/audit | |||
project_file_read | Read the content of a file | get_content | GET /v1/projects/{projectId}/files/content | |
placement_read | Read agent placements and the registered Agents that can be placed | list | GET /v1/projects/{projectId}/placements | |
get | GET /v1/projects/{projectId}/placements/{placementId} | |||
list_agent_candidates | GET /v1/projects/agent-candidates | |||
run_read | Read workflow runs and their artifacts | list | GET /v1/projects/{projectId}/runs | |
get | GET /v1/projects/{projectId}/runs/{runId} | ✅ | ||
get_config | GET /v1/projects/{projectId}/runs/{runId}/config | |||
list_artifacts | GET /v1/projects/{projectId}/artifacts | |||
get_artifact_content | GET /v1/projects/{projectId}/artifacts/{artifactId}/content | |||
execution_read | Read agent executions | list | GET /v1/projects/{projectId}/executions | |
get | GET /v1/projects/{projectId}/executions/{executionId} | |||
list_operations | GET /v1/projects/{projectId}/executions/{executionId}/operations | |||
get_timeline | GET /v1/projects/{projectId}/executions/{executionId}/timeline | |||
workitem_read | Read work items | list | GET /v1/workitems | |
get | GET /v1/workitems/{workItemId} | |||
connector_read | Read connectors (MCP servers and A2A agents) | get_mcp | GET /v1/connectors/mcp/{connectionId} | |
get_a2a | GET /v1/connectors/a2a/{connectionId} | |||
project_write | Create and change projects | create | POST /v1/projects | |
update | PATCH /v1/projects/{projectId} | |||
step_write | Add, change, reorder, and delete steps | create | POST /v1/projects/{projectId}/steps | |
update | PATCH /v1/projects/{projectId}/steps/{stepId} | |||
reorder | PUT /v1/projects/{projectId}/steps/order | |||
delete | DELETE /v1/projects/{projectId}/steps/{stepId} | |||
placement_write | Place registered Agents and change placements | create | POST /v1/projects/{projectId}/placements | |
delete | DELETE /v1/projects/{projectId}/placements/{placementId} | |||
update_steps | PUT /v1/projects/{projectId}/placements/{placementId}/steps | |||
update_schedule | PATCH /v1/projects/{projectId}/placements/{placementId}/schedule | |||
project_run | Start workflow runs, fire triggers, and change the reviewers and deadline of a workflow run | start_run | POST /v1/projects/{projectId}/runs | ✅ |
fire_trigger | POST /v1/projects/{projectId}/triggers/{triggerId}/fire | ✅ | ||
reassign_approvers | PUT /v1/projects/{projectId}/runs/{runId}/approvers | |||
set_deadline | PATCH /v1/projects/{projectId}/runs/{runId} | |||
project_delete | Delete a project | — | DELETE /v1/projects/{projectId} | |
workitem_decide | Decide work items and extend their due dates | decide (optional) | POST /v1/workitems/{workItemId}/decision | |
extend | PATCH /v1/workitems/{workItemId} |
- Arguments: Path values (such as
projectId), queries, and body fields are each passed as a separate argument (the body is not wrapped inbody). Their names and meanings are in the input schema of each tool returned bytools/list.list_agent_candidatesofplacement_readtakesprojectType, andlist_artifactsofrun_readtakesrunId(they correspond to the REST queriesproject_typeandrun_id; theparamof an error also uses the argument name).methodofworkitem_decidecan be omitted (it then meansdecide). The 8 read tools (names ending in_read) and the delete tool (project_delete) reject arguments that are not in the input schema. The 5 write tools do not reject them in MCP, but only the arguments in the input schema are used. In operations that take a body, unknown arguments are passed to REST as body fields and REST decides. The 2 operations that take no body (deleteofstep_writeanddeleteofplacement_write) do not use them - Response: On success, the same JSON as REST is returned as the structured result (
structuredContent) and one text that is that JSON. Exception:get_contentofproject_file_readandget_artifact_contentofrun_readreturn not the same JSON as REST but the same form asget_file_content(text, an image, or base64; over 5 MB, a URL of the REST endpoint that takes the same token as MCP) - Errors: The same shape as REST (
{"error":{"type","message","code","param","suggested_action"}};paramandsuggested_actiononly when present) is returned as a tool error (isError: true).typeandcodeare the same as REST.message,param, andsuggested_actionuse the MCP argument and tool names, except that amessagereturned from the backend is returned as is. Arguments that do not match the input schema (a wrong type, an unknown name, a wrongscheduleform, and so on) return not the REST shape but a tool error with the textInput validation error: …(with the field name), without a structured result - Annotations: Read tools have
readOnlyHint: true, and write and delete tools havedestructiveHint: true. Every tool in the project set hasopenWorldHint: false. The 5 frequently used read tools (project_read,project_status_read,workitem_read,execution_read, andrun_read) have_meta["anthropic/alwaysLoad"], so clients that load tools later load them from the start.workitem_decidehas_meta["anthropic/requiresUserInteraction"], and Claude Code asks the user to approve every call (in itsdontAskmode, or in non-interactive mode with--permission-prompt-tool, the call is denied) - Resend key: The
Idempotency-Keyheader of REST is passed as the argumentidempotencyKey - System integrations: Only the four operations marked with ✅ under "System integration" can be used. Other operations return a tool error (
forbidden)
Published Set
The set that offers each workflow project published by its owner as one tool. AI clients can call a published project as a counterpart that runs when asked.
| Tool | Description |
|---|---|
prj_<name> | Starts a workflow run of the published project. The name is the one the owner gave in the publication settings. The description is the owner's description followed by a fixed text |
get_project_run | Reads the status, steps, and results of a workflow run started by a published tool |
- It can be called with a system integration token and with a user token of the owner of the project (the same applies to
get_project_run). A user who is not a member gets aproject_not_foundtool error, and a member who is not an owner gets anowner_onlytool error - When no project is published, the set is empty (
get_project_runis not listed either). The list does not change with the kind of token - The tool of a project whose publication was stopped disappears from the list within about 60 seconds. Calling it after that returns a
project_not_foundtool error, and no run starts. When the list of published projects cannot be read, the tool error can be retried later - Annotations:
prj_<name>hasreadOnlyHint: false,destructiveHint: false, andopenWorldHint: true.get_project_runhasreadOnlyHint: true
What AGENTIC STAR offers, and the endpoints that call each, are as follows.
| What is offered | REST | MCP |
|---|---|---|
| Conversations with Agents | Chat API (POST /v1/chat/completions) | The chat set (execute_chat) |
| Project features (create, change, run, read) | User API Reference (Projects) and System Integration API Reference | The project set |
| Published workflows (offered as counterparts that run when asked) | — | The published set |
Limits
The values in the table are defaults. They can change with the settings of the environment.
| Item | Limit |
|---|---|
| Request body | Up to 30 MB. Beyond that, 413 Payload Too Large |
Files attached to execute_chat | Up to 5 files, 5 MB per file, 20 MB in total (sizes before base64 encoding) |
Reading file content (get_file_content, get_content of project_file_read, and get_artifact_content of run_read) | Over 5 MB, a download URL that takes the same token is returned instead of the content |
payload of a published tool (prj_<name>) | Up to 8,000 characters as JSON and up to 16 KB in UTF-8. It is passed to the Agent of the first step of the workflow as JSON data (it does not become an attached file) |
execute_chat in the same conversation | One at a time. Sending while the previous call is running returns an error (CONVERSATION_BUSY) |
Time taken by execute_chat | It depends on the registered Agent. It can take several minutes and exceed a client timeout of 6 minutes. When there is no progress for about 30 minutes, or 2 hours after the start, the run is cut off and an error (EXECUTION_TIMEOUT) is returned. Even then the result is saved and can be read with list_conversation_messages |
Errors
These are the errors returned over HTTP when connecting. Errors from calling a tool are returned as tool errors (isError: true) (Provided Tools).
| HTTP Status | Description |
|---|---|
400 Bad Request | For example, the value of the MCP-Protocol-Version header is not in Supported Protocol Versions |
401 Unauthorized | Access token missing, invalid, or expired |
404 Not Found | The MCP inbound endpoint is not open in the environment, or a user token obtained in a way other than sign-in from an external tool |
405 Method Not Allowed | A method other than POST (such as GET). The endpoint does not offer a server stream (SSE) opened with GET, or sessions |
413 Payload Too Large | The request body exceeds the limit (Limits) |
See Also
- AI Client Connection Guide (MCP) — Client configuration and how to connect
- Connection Methods Guide — Overview of connection methods
- Authentication API Reference — Token acquisition
- User API Reference (Conversations, Organizations) — REST equivalents of the chat set
- User API Reference (Projects) — REST equivalents of the project set
- Model Context Protocol Specification — Protocol details