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 (a request without a valid token gets 401 Unauthorized first). 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 and on the organization operations role |
| System integration (service account) token | Client Credentials flow (Authentication guide) | The tools of the chat toolset, 9 operations of the project toolset (list of project_read, get of run_read, list_artifacts, get_artifact_content, get of execution_read (status fields only), start_run, fire_trigger, cancel_run, and cancel_execution of project_run), and the tools of the published toolset |
- 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 toolset (17 tools) |
?toolsets=published | The published set (one tool per published project, and get_project_run and cancel_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. When a user whose use was suspended by an administrator calls a tool other than list_agents (and cancel_chat when no task is in progress), errorCode is UNAUTHENTICATED and the text is User suspended.
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 console. When it is not written, it is the Agent's description in the admin console, 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 toolset
The 17 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 | |||
export_definition | GET /v1/projects/{projectId}/definition | |||
get_definition_approval | GET /v1/projects/{projectId}/definition-approval | |||
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, their artifacts, and their case config | list | GET /v1/projects/{projectId}/runs | |
get | GET /v1/projects/{projectId}/runs/{runId} | ✅ | ||
get_config | GET /v1/projects/{projectId}/runs/{runId}/config | |||
get_case_config | GET /v1/projects/{projectId}/runs/{runId}/case-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} | ✅ (status fields only) | ||
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} | |||
webhook_read | Read project webhooks and their deliveries | list | GET /v1/projects/{projectId}/webhooks | |
list_deliveries | GET /v1/projects/{projectId}/webhooks/{webhookId}/deliveries | |||
project_write | Create and change projects | create | POST /v1/projects | |
update | PATCH /v1/projects/{projectId} | |||
import | POST /v1/projects/import | |||
dismiss_relink | DELETE /v1/projects/{projectId}/relink | |||
withdraw_definition | DELETE /v1/projects/{projectId}/definition-approval | |||
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 | |||
update_runtime_config | PUT /v1/projects/{projectId}/placements/{placementId}/steps/{stepId}/runtime-config | |||
trigger_write | Create, change, and delete triggers | create | POST /v1/projects/{projectId}/triggers | |
update | PATCH /v1/projects/{projectId}/triggers/{triggerId} | |||
delete | DELETE /v1/projects/{projectId}/triggers/{triggerId} | |||
webhook_write | Create, change, and delete project webhooks (secret is not returned) | create | POST /v1/projects/{projectId}/webhooks | |
update | PATCH /v1/projects/{projectId}/webhooks/{webhookId} | |||
delete | DELETE /v1/projects/{projectId}/webhooks/{webhookId} | |||
project_run | Start workflow runs, upload input files, fire triggers, change the reviewers and deadline of a workflow run, replace the case config of a workflow run waiting for review, cancel workflow runs, and stop sweep executions of cycle projects | start_run | POST /v1/projects/{projectId}/runs | ✅ |
upload_input | POST /v1/projects/{projectId}/artifacts | |||
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} | |||
update_run_config | PUT /v1/projects/{projectId}/runs/{runId}/case-config | |||
cancel_run | POST /v1/projects/{projectId}/runs/{runId}/cancel | ✅ | ||
cancel_execution | POST /v1/projects/{projectId}/executions/{executionId}/cancel | ✅ | ||
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 9 read tools (names ending in_read) and the delete tool (project_delete) reject arguments that are not in the input schema. The 7 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 4 operations that take no body (deleteofstep_write,deleteofplacement_write,deleteoftrigger_write, anddeleteofwebhook_write) do not use them.upload_inputofproject_runtakes the file content ascontent(text; setencodingto"base64"for binary files; the default is"utf-8") and the name and format asnameandformat.idempotencyKeyis optional.update_runtime_configofplacement_writetakesplacementIdandstepIdas path valuesgetandget_controlofproject_readandlistandgetofplacement_readread the view with the pending definition change laid over it with the argumentdefinition("pending").withdraw_definitionofproject_writespecifies the pending change to withdraw with the argumentpendingDigest. - 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) In a tenant that requires approval for definition changes, the results of the write tools (project_write,step_write,placement_writeandtrigger_write) includedefinitionApproval, as in REST (a change that became pending does not affect runs until it is approved). - 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. When a user whose use was suspended by an administrator calls a tool,codeisaccount_suspended - Annotations: Read tools have
readOnlyHint: true, and write and delete tools havedestructiveHint: true. All tools of the project toolset haveopenWorldHint: false. The 5 frequently used read tools (project_read,project_status_read,workitem_read,execution_read,run_read) have_meta["anthropic/alwaysLoad"], so they are loaded from the start even by clients that load tools later.workitem_decidehas_meta["anthropic/requiresUserInteraction"], and Claude Code asks the user for approval every time it is called (it is refused indontAskmode and in non-interactive runs that use--permission-prompt-tool) - Resend key: The
Idempotency-Keyheader of REST is passed as the argumentidempotencyKey - System integrations: Only the nine 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 |
cancel_project_run | Cancels a workflow run started by a published tool (this cannot be undone) |
- It can be called with a system integration token and with a user token of a participant of the project (owner, operator or member) or of a person with the organization operations role (the same applies to
get_project_run). Withcancel_project_run, a workflow run someone else started can be stopped with a system integration token and by owners, operators and people with the organization operations role; a member gets anoperator_onlytool error. A user who is neither gets aproject_not_foundtool error - For a project whose first definition is waiting for approval, and for a project in which references missing after the import have not been reconnected,
prj_<name>does not start, and returns a tool error (definition_pendingorrelink_required) - When no project is published, the set is empty (
get_project_runandcancel_project_runare 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, andcancel_project_runhasreadOnlyHint: false,destructiveHint: true, andopenWorldHint: false
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), System Integration API Reference | Project toolset |
| 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 |
Content of upload_input of project_run | Up to 20 MB for "binary" and 1 MB for the other formats (decoded size). Larger content returns a tool error (file_too_large) |
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) — the REST endpoints for the project toolset
- Model Context Protocol Specification — Protocol details