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. 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
A system integration (service account) tokenClient 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.

QueryAvailable tools
None, or ?toolsets=chatThe chat set (5 tools)
?toolsets=projectThe project set (14 tools)
?toolsets=publishedThe published set (one tool per published project, and get_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.

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.

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 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.

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
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 and their artifactslistGET /v1/projects/{projectId}/runs
getGET /v1/projects/{projectId}/runs/{runId}✅
get_configGET /v1/projects/{projectId}/runs/{runId}/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}
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}
project_writeCreate and change projectscreatePOST /v1/projects
updatePATCH /v1/projects/{projectId}
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
project_runStart workflow runs, fire triggers, and change the reviewers and deadline of a workflow runstart_runPOST /v1/projects/{projectId}/runs✅
fire_triggerPOST /v1/projects/{projectId}/triggers/{triggerId}/fire✅
reassign_approversPUT /v1/projects/{projectId}/runs/{runId}/approvers
set_deadlinePATCH /v1/projects/{projectId}/runs/{runId}
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 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 (delete of step_write and delete of placement_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_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)
  • 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
  • Annotations: Read tools have readOnlyHint: true, and write and delete tools have destructiveHint: true. Every tool in the project set has openWorldHint: false. The 5 frequently used read tools (project_read, project_status_read, workitem_read, execution_read, and run_read) have _meta["anthropic/alwaysLoad"], so clients that load tools later load them from the start. workitem_decide has _meta["anthropic/requiresUserInteraction"], and Claude Code asks the user to approve every call (in its dontAsk mode, or in non-interactive mode with --permission-prompt-tool, the call is denied)
  • Resend key: The Idempotency-Key header of REST is passed as the argument idempotencyKey
  • 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.

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
  • 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 a project_not_found tool error, and a member who is not an owner gets an owner_only tool error
  • When no project is published, the set is empty (get_project_run is 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

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) and System Integration API ReferenceThe 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.

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
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​