Skip to main content

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.

Where MCP is available

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.

Marketplace
https://<your-domain>

Endpoint​

MethodEndpointDescription
POST/api/v1/mcpMCP 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.

TokenHow to get itAvailable 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) tokenClient 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.

QueryAvailable tools
None, or ?toolsets=chatThe chat set (5 tools)
?toolsets=projectThe project toolset (17 tools)
?toolsets=publishedThe published set (one tool per published project, and get_project_run and cancel_project_run)
?toolsets=chat,project,publishedAll three sets

Example: https://<your-domain>/api/v1/mcp?toolsets=chat,project

  • Unknown names are ignored and reported at the beginning of instructions in the response to initialize (or server/discover). If no known name is given, only the chat set is used
  • The tools returned by tools/list depend 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) returns forbidden

Supported Protocol Versions​

The endpoint accepts the following MCP protocol revisions. Clients of both the new and the earlier style can connect.

RevisionConnection style
2026-07-28The protocol version and client capabilities are sent on every request (initialize is not used)
2025-11-25The version is negotiated with initialize
2025-06-18The version is negotiated with initialize
2025-03-26The version is negotiated with initialize
2024-11-05The version is negotiated with initialize
2024-10-07The version is negotiated with initialize

Provided Tools​

The tools available via tools/call are as follows for each tool set.

Chat Set​

ToolDescription
execute_chatSend a task to a registered Agent and get the result
get_file_contentGet a deliverable file
cancel_chatCancel a running task
list_agentsGet the list of registered Agents that execute_chat can run
list_conversation_messagesRead 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.

Treat tool results as data, not instructions

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.

ToolPurposemethodREST equivalentSystem integration
project_readRead projectslistGET /v1/projects✅
list_sharedGET /v1/projects/shared
getGET /v1/projects/{projectId}
get_controlGET /v1/projects/{projectId}/control
list_organizationsGET /v1/projects/organizations
export_definitionGET /v1/projects/{projectId}/definition
get_definition_approvalGET /v1/projects/{projectId}/definition-approval
project_status_readRead the queue, KPIs, and records (audit trail)list_my_queueGET /v1/queue
list_queueGET /v1/projects/{projectId}/queue
get_kpiGET /v1/projects/{projectId}/kpi
list_audit_eventsGET /v1/projects/{projectId}/audit
project_file_readRead the content of a fileget_contentGET /v1/projects/{projectId}/files/content
placement_readRead agent placements and the registered Agents that can be placedlistGET /v1/projects/{projectId}/placements
getGET /v1/projects/{projectId}/placements/{placementId}
list_agent_candidatesGET /v1/projects/agent-candidates
run_readRead workflow runs, their artifacts, and their case configlistGET /v1/projects/{projectId}/runs
getGET /v1/projects/{projectId}/runs/{runId}✅
get_configGET /v1/projects/{projectId}/runs/{runId}/config
get_case_configGET /v1/projects/{projectId}/runs/{runId}/case-config
list_artifactsGET /v1/projects/{projectId}/artifacts✅
get_artifact_contentGET /v1/projects/{projectId}/artifacts/{artifactId}/content✅
execution_readRead agent executionslistGET /v1/projects/{projectId}/executions
getGET /v1/projects/{projectId}/executions/{executionId}✅ (status fields only)
list_operationsGET /v1/projects/{projectId}/executions/{executionId}/operations
get_timelineGET /v1/projects/{projectId}/executions/{executionId}/timeline
workitem_readRead work itemslistGET /v1/workitems
getGET /v1/workitems/{workItemId}
connector_readRead connectors (MCP servers and A2A agents)get_mcpGET /v1/connectors/mcp/{connectionId}
get_a2aGET /v1/connectors/a2a/{connectionId}
webhook_readRead project webhooks and their deliverieslistGET /v1/projects/{projectId}/webhooks
list_deliveriesGET /v1/projects/{projectId}/webhooks/{webhookId}/deliveries
project_writeCreate and change projectscreatePOST /v1/projects
updatePATCH /v1/projects/{projectId}
importPOST /v1/projects/import
dismiss_relinkDELETE /v1/projects/{projectId}/relink
withdraw_definitionDELETE /v1/projects/{projectId}/definition-approval
step_writeAdd, change, reorder, and delete stepscreatePOST /v1/projects/{projectId}/steps
updatePATCH /v1/projects/{projectId}/steps/{stepId}
reorderPUT /v1/projects/{projectId}/steps/order
deleteDELETE /v1/projects/{projectId}/steps/{stepId}
placement_writePlace registered Agents and change placementscreatePOST /v1/projects/{projectId}/placements
deleteDELETE /v1/projects/{projectId}/placements/{placementId}
update_stepsPUT /v1/projects/{projectId}/placements/{placementId}/steps
update_schedulePATCH /v1/projects/{projectId}/placements/{placementId}/schedule
update_runtime_configPUT /v1/projects/{projectId}/placements/{placementId}/steps/{stepId}/runtime-config
trigger_writeCreate, change, and delete triggerscreatePOST /v1/projects/{projectId}/triggers
updatePATCH /v1/projects/{projectId}/triggers/{triggerId}
deleteDELETE /v1/projects/{projectId}/triggers/{triggerId}
webhook_writeCreate, change, and delete project webhooks (secret is not returned)createPOST /v1/projects/{projectId}/webhooks
updatePATCH /v1/projects/{projectId}/webhooks/{webhookId}
deleteDELETE /v1/projects/{projectId}/webhooks/{webhookId}
project_runStart 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 projectsstart_runPOST /v1/projects/{projectId}/runs✅
upload_inputPOST /v1/projects/{projectId}/artifacts
fire_triggerPOST /v1/projects/{projectId}/triggers/{triggerId}/fire✅
reassign_approversPUT /v1/projects/{projectId}/runs/{runId}/approvers
set_deadlinePATCH /v1/projects/{projectId}/runs/{runId}
update_run_configPUT /v1/projects/{projectId}/runs/{runId}/case-config
cancel_runPOST /v1/projects/{projectId}/runs/{runId}/cancel✅
cancel_executionPOST /v1/projects/{projectId}/executions/{executionId}/cancel✅
project_deleteDelete a project—DELETE /v1/projects/{projectId}
workitem_decideDecide work items and extend their due datesdecide (optional)POST /v1/workitems/{workItemId}/decision
extendPATCH /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 in body). Their names and meanings are in the input schema of each tool returned by tools/list. list_agent_candidates of placement_read takes projectType, and list_artifacts of run_read takes runId (they correspond to the REST queries project_type and run_id; the param of an error also uses the argument name). method of workitem_decide can be omitted (it then means decide). 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 (delete of step_write, delete of placement_write, delete of trigger_write, and delete of webhook_write) do not use them. upload_input of project_run takes the file content as content (text; set encoding to "base64" for binary files; the default is "utf-8") and the name and format as name and format. idempotencyKey is optional. update_runtime_config of placement_write takes placementId and stepId as path values get and get_control of project_read and list and get of placement_read read the view with the pending definition change laid over it with the argument definition ("pending"). withdraw_definition of project_write specifies the pending change to withdraw with the argument pendingDigest.
  • Response: On success, the same JSON as REST is returned as the structured result (structuredContent) and one text that is that JSON. Exception: get_content of project_file_read and get_artifact_content of run_read return not the same JSON as REST but the same form as get_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_write and trigger_write) include definitionApproval, 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"}}; param and suggested_action only when present) is returned as a tool error (isError: true). type and code are the same as REST. message, param, and suggested_action use the MCP argument and tool names, except that a message returned from the backend is returned as is. Arguments that do not match the input schema (a wrong type, an unknown name, a wrong schedule form, and so on) return not the REST shape but a tool error with the text Input validation error: … (with the field name), without a structured result. When a user whose use was suspended by an administrator calls a tool, code is account_suspended
  • Annotations: Read tools have readOnlyHint: true, and write and delete tools have destructiveHint: true. All tools of the project toolset have openWorldHint: 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_decide has _meta["anthropic/requiresUserInteraction"], and Claude Code asks the user for approval every time it is called (it is refused in dontAsk mode and in non-interactive runs that use --permission-prompt-tool)
  • Resend key: The Idempotency-Key header of REST is passed as the argument idempotencyKey
  • 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.

ToolDescription
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_runReads the status, steps, and results of a workflow run started by a published tool
cancel_project_runCancels 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). With cancel_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 an operator_only tool error. A user who is neither gets a project_not_found tool 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_pending or relink_required)
  • When no project is published, the set is empty (get_project_run and cancel_project_run are 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_found tool error, and no run starts. When the list of published projects cannot be read, the tool error can be retried later
  • Annotations: prj_<name> has readOnlyHint: false, destructiveHint: false, and openWorldHint: true. get_project_run has readOnlyHint: true, and cancel_project_run has readOnlyHint: false, destructiveHint: true, and openWorldHint: false

What AGENTIC STAR offers, and the endpoints that call each, are as follows.

What is offeredRESTMCP
Conversations with AgentsChat API (POST /v1/chat/completions)The chat set (execute_chat)
Project features (create, change, run, read)User API Reference (Projects), System Integration API ReferenceProject 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.

ItemLimit
Request bodyUp to 30 MB. Beyond that, 413 Payload Too Large
Files attached to execute_chatUp 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_runUp 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 conversationOne at a time. Sending while the previous call is running returns an error (CONVERSATION_BUSY)
Time taken by execute_chatIt 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 StatusDescription
400 Bad RequestFor example, the value of the MCP-Protocol-Version header is not in Supported Protocol Versions
401 UnauthorizedAccess token missing, invalid, or expired
404 Not FoundThe 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 AllowedA method other than POST (such as GET). The endpoint does not offer a server stream (SSE) opened with GET, or sessions
413 Payload Too LargeThe request body exceeds the limit (Limits)

See Also​