MCP API Reference
Detailed specification of the MCP (Model Context Protocol) endpoint provided by the AGENTIC STAR SaaS edition. MCP is the interface used by MCP-capable AI agents (such as Claude) to connect to AGENTIC STAR and execute tasks, retrieve files, and work with projects via tool calls.
This reference describes MCP in the SaaS edition. For MCP in the Marketplace edition, see the MCP API Reference (Marketplace).
For client configuration and how to connect, see the 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.
https://api.fd.agenticstar.tm.softbank.jpEndpoint
| 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 token needs one of the following scopes. A token with neither gets 403 Forbidden.
| Scope | Purpose |
|---|---|
mcp:all | Use all MCP tools. No other scope is needed |
mcp:connect | Connect to MCP. Which tools (for the project set, which operations) you can use depends on the other scopes you hold (see "Required scope" in the tables of Provided Tools) |
mcp:connect for new appsFor a new app, attach mcp:connect and only the scopes required by the tools you use. mcp:all is the scope that can use every MCP tool.
mcp:allAn app with mcp:all can use the tools of the project set by selecting project in the tool sets. list_conversation_messages, which reads conversations, is available without selecting anything.
For system integrations (Client Credentials flow), you can select mcp:connect, project:read, and project:run. A system integration can use the five operations of the project set (list of project_read, get of run_read, and start_run, fire_trigger, and cancel_run of project_run) and list_personas of the chat set, only within the project restriction of the system integration.
A system integration can also connect by sending an API key issued in the Console in Authorization: Bearer (see Console Guide — API Key).
For token acquisition, see the Authentication API Reference (SaaS).
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 (6 tools) |
?toolsets=project | The project set (27 tools) |
?toolsets=chat,project | Both (33 tools) |
Example: https://api.fd.agenticstar.tm.softbank.jp/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 scopes of the token. When you call a tool without the required scope, a tool error (isError: true) returns the scope needed and what to do next
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. "Required scope" is not checked for a token with mcp:all. A token with mcp:connect also needs that scope.
Chat Set
| Tool | Description | Required scope (with mcp:connect) |
|---|---|---|
execute_chat | Send a task to an agent and get the result | chat:exec (plus chat:file when attaching files) |
get_file_content | Get a deliverable file | chat:exec |
get_ui_resource | Get the HTML of a UI resource | chat:exec |
cancel_chat | Cancel a running task | chat:exec |
list_personas | Get the list of personas | None (mcp:connect alone is enough) |
list_conversation_messages | Read the messages of your conversation | chat:history |
A system integration token cannot hold chat:* scopes, so list_personas is the only tool of the chat set it can use.
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_personas (and cancel_chat when no task is in progress), errorCode is UNAUTHENTICATED and the text is User suspended.
With list_conversation_messages, conversations of project executions can also be read, only by the owner of the project at the time of the execution.
The responses of execute_chat and list_conversation_messages hold the results of the tools the agent used, as stored. So does the HTML that get_ui_resource returns. These include responses from external MCP servers that an administrator allowed to connect. AGENTIC STAR does not inspect their content.
get_ui_resource returns the HTML as is, and it uses that much of the context. Check uiResources[].size (bytes) first, and if it is large, ask the user before calling. size may be absent.
Drafts (drafts[])
When you ask the chat for a draft of a playbook, skill, project, agent change or schedule, the drafts go into structuredContent.drafts[] of execute_chat in the order they appeared, and only then is structuredContent.draftsNote (an English note for the model) added. A response with no draft has neither the drafts key nor the draftsNote key (as with uiResources). The shape of each element and how to create it are the same as in Streaming guide — delta.draft. In list_conversation_messages, it is in metadata.draft of each task.
The tools that create from a draft (playbook_write, skill_write, import of project_write, and agent_write) exist only when you connect with the project set (?toolsets=chat,project), and an mcp:connect token also needs their scopes (assets:write; project:write for import). To find an existing one by name and change it, the read scopes are also needed (assets:read, plus project:read to narrow agents by placements). Without them, tell the user to save it on the screen. Before creating, confirm with the user, and do not also have it saved on the screen. Change an existing one only when exactly one matches the name (for an agent, first narrow by the placements of the project when projectName is set). Schedules cannot be created (the user creates them in the scheduled runs on the screen).
Project Set
The 27 tools that work with projects, runs, work items, the queue, the project library, and the library (Agents, Playbooks, Skills). 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 Project API Reference (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 | Required scope (with mcp:connect) | System integration |
|---|---|---|---|---|---|
project_read | Read projects | list | GET /v1/projects | project:read | ✅ |
list_shared | GET /v1/projects/shared | project:read | |||
get | GET /v1/projects/{projectId} | project:read | |||
get_control | GET /v1/projects/{projectId}/control | project:read | |||
list_organizations | GET /v1/projects/organizations | project:read | |||
list_automation_destinations | GET /v1/projects/automation-destinations | project:read | |||
export_definition | GET /v1/projects/{projectId}/definition | project:read | |||
get_definition_approval | GET /v1/projects/{projectId}/definition-approval | project:read | |||
project_status_read | Read the queue, KPI, and records (audit trail) | list_my_queue | GET /v1/queue | project:read | |
list_queue | GET /v1/projects/{projectId}/queue | project:read | |||
get_kpi | GET /v1/projects/{projectId}/kpi | project:read | |||
get_kpi_trends | GET /v1/projects/{projectId}/kpi/trends | project:read | |||
list_audit_events | GET /v1/projects/{projectId}/audit | project:read | |||
project_file_read | Read the project library and the content of files | list | GET /v1/projects/{projectId}/library | project:read | |
list_versions | GET /v1/projects/{projectId}/library/{fileId}/versions | project:read | |||
get_content | GET /v1/projects/{projectId}/files/content | project:read | |||
placement_read | Read agent placements | list | GET /v1/projects/{projectId}/placements | project:read | |
get | GET /v1/projects/{projectId}/placements/{placementId} | project:read | |||
get_memory_candidates | GET /v1/projects/{projectId}/memory-candidates | project:read | |||
run_read | Read workflow runs | list | GET /v1/projects/{projectId}/runs | project:read | |
get | GET /v1/projects/{projectId}/runs/{runId} | project:read | ✅ | ||
get_config | GET /v1/projects/{projectId}/runs/{runId}/config | project:read | |||
get_resume_options | GET /v1/projects/{projectId}/runs/{runId}/resume | project:read | |||
execution_read | Read agent executions | list | GET /v1/projects/{projectId}/executions | project:read | |
get | GET /v1/projects/{projectId}/executions/{executionId} | project:read | |||
list_operations | GET /v1/projects/{projectId}/executions/{executionId}/operations | project:read | |||
get_timeline | GET /v1/projects/{projectId}/executions/{executionId}/timeline | project:read | |||
workitem_read | Read work items (approval requests) | list | GET /v1/workitems | project:read | |
get | GET /v1/workitems/{workItemId} | project:read | |||
connector_read | Read connections (MCP servers, A2A agents) | get_mcp | GET /v1/connectors/mcp/{connectionId} | project:read | |
get_a2a | GET /v1/connectors/a2a/{connectionId} | project:read | |||
webhook_read | Read project webhooks and their deliveries | list | GET /v1/projects/{projectId}/webhooks | project:read | |
list_deliveries | GET /v1/projects/{projectId}/webhooks/{webhookId}/deliveries | project:read | |||
agent_read | Read Agents in the library | list | GET /v1/agents | assets:read | |
list_shared | GET /v1/agents/shared | assets:read | |||
get | GET /v1/agents/{agentId} | assets:read | |||
playbook_read | Read Playbooks in the library | list | GET /v1/playbooks | assets:read or chat:exec | |
list_shared | GET /v1/playbooks/shared | assets:read or chat:exec | |||
get | GET /v1/playbooks/{playbookId} | assets:read | |||
skill_read | Read Skills in the library | list | GET /v1/skills | assets:read or chat:exec | |
list_shared | GET /v1/skills/shared | assets:read or chat:exec | |||
get | GET /v1/skills/{skillId} | assets:read | |||
list_versions | GET /v1/skills/{skillId}/versions | assets:read | |||
list_files | GET /v1/skills/{skillId}/files | assets:read | |||
get_file | GET /v1/skills/{skillId}/files/content | assets:read | |||
project_write | Create or change projects | create | POST /v1/projects | project:write | |
update | PATCH /v1/projects/{projectId} | project:write | |||
import | POST /v1/projects/import | project:write | |||
dismiss_relink | DELETE /v1/projects/{projectId}/relink | project:write | |||
withdraw_definition | DELETE /v1/projects/{projectId}/definition-approval | project:write | |||
project_file_write | Add, change, and delete files in the project library | upload | POST /v1/projects/{projectId}/library | project:write | |
copy | POST /v1/projects/{projectId}/library/copy | project:write | |||
update_content | PUT /v1/projects/{projectId}/library/{fileId}/content | project:write | |||
restore | POST /v1/projects/{projectId}/library/{fileId}/restore | project:write | |||
import_latest | POST /v1/projects/{projectId}/library/{fileId}/import-latest | project:write | |||
delete | DELETE /v1/projects/{projectId}/library/{fileId} | project:write | |||
step_write | Add, change, reorder, or delete steps | create | POST /v1/projects/{projectId}/steps | project:write | |
update | PATCH /v1/projects/{projectId}/steps/{stepId} | project:write | |||
reorder | PUT /v1/projects/{projectId}/steps/order | project:write | |||
delete | DELETE /v1/projects/{projectId}/steps/{stepId} | project:write | |||
placement_write | Place agents, change placements, and bind files to steps | create | POST /v1/projects/{projectId}/placements | project:write | |
delete | DELETE /v1/projects/{projectId}/placements/{placementId} | project:write | |||
update_steps | PUT /v1/projects/{projectId}/placements/{placementId}/steps | project:write | |||
update_memory | PATCH /v1/projects/{projectId}/placements/{placementId}/memory | project:write | |||
update_instruction | PATCH /v1/projects/{projectId}/placements/{placementId}/instruction | project:write | |||
update_schedule | PATCH /v1/projects/{projectId}/placements/{placementId}/schedule | project:write | |||
update_library_bindings | PUT /v1/projects/{projectId}/placements/{placementId}/library-bindings | project:write | |||
trigger_write | Create, change, and delete triggers | create | POST /v1/projects/{projectId}/triggers | project:write | |
update | PATCH /v1/projects/{projectId}/triggers/{triggerId} | project:write | |||
delete | DELETE /v1/projects/{projectId}/triggers/{triggerId} | project:write | |||
webhook_write | Create, change, and delete project webhooks (secret is not returned) | create | POST /v1/projects/{projectId}/webhooks | project:write | |
update | PATCH /v1/projects/{projectId}/webhooks/{webhookId} | project:write | |||
delete | DELETE /v1/projects/{projectId}/webhooks/{webhookId} | project:write | |||
project_run | Start a workflow run, fire a trigger, run a failed sweep execution again, change the reviewers and deadline of a workflow run, resume a closed workflow run, or cancel a workflow run | start_run | POST /v1/projects/{projectId}/runs | project:run | ✅ |
fire_trigger | POST /v1/projects/{projectId}/triggers/{triggerId}/fire | project:run | ✅ | ||
rerun_execution | POST /v1/projects/{projectId}/executions/{executionId}/rerun | project:run | |||
reassign_approvers | PUT /v1/projects/{projectId}/runs/{runId}/approvers | project:write | |||
set_deadline | PATCH /v1/projects/{projectId}/runs/{runId} | project:write | |||
resume_run | POST /v1/projects/{projectId}/runs/{runId}/resume | project:run | |||
cancel_run | POST /v1/projects/{projectId}/runs/{runId}/cancel | project:run | ✅ | ||
project_delete | Delete a project | — | DELETE /v1/projects/{projectId} | project:delete | |
workitem_decide | Decide a work item or extend its due date | decide (optional) | POST /v1/workitems/{workItemId}/decision | project:decide | |
extend | PATCH /v1/workitems/{workItemId} | project:decide | |||
agent_write | Create, change, or copy Agents | create | POST /v1/agents | assets:write | |
update | PATCH /v1/agents/{agentId} | assets:write | |||
copy | POST /v1/agents/{agentId}/copy | assets:write | |||
playbook_write | Create, change, or copy Playbooks | create | POST /v1/playbooks | assets:write | |
update | PATCH /v1/playbooks/{playbookId} | assets:write | |||
copy | POST /v1/playbooks/{playbookId}/copy | assets:write | |||
skill_write | Create Skills, change their files and settings, or copy them | create | POST /v1/skills | assets:write | |
replace_files | PUT /v1/skills/{skillId}/files | assets:write | |||
edit_files | PATCH /v1/skills/{skillId}/files | assets:write | |||
update_settings | PATCH /v1/skills/{skillId} | assets:write | |||
copy | POST /v1/skills/{skillId}/copy | assets:write | |||
agent_delete | Delete an Agent | — | DELETE /v1/agents/{agentId} | assets:delete | |
playbook_delete | Delete a Playbook | — | DELETE /v1/playbooks/{playbookId} | assets:delete | |
skill_delete | Delete a Skill | — | DELETE /v1/skills/{skillId} | assets:delete |
- 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. Exceptions:uploadandupdate_contentofproject_file_writesend the file not asmultipart/form-databut as the argumentscontent(the content) andencoding(utf-8orbase64; the default isutf-8).uploadalso sendsfilename(the name in the library).methodofworkitem_decidecan be omitted (it then meansdecide). The 12 read tools (names ending in_read) and the 4 delete tools (names ending in_delete) reject arguments that are not in the input schema. The 11 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 10 operations that take no body (deleteofstep_write,deleteofplacement_write,deleteoftrigger_write,deleteofwebhook_write,rerun_executionofproject_run,copyofagent_writeandplaybook_write, andupload,update_content, anddeleteofproject_file_write) do not use themgetandget_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.createandupdateofstep_writeaccept the argumentautomationConfig(settings of external automation).defaultZonealso accepts"branch", andupdatealso accepts the argumentbranchConfig(settings of a branch). - Values and files for the next step:
step_writecreateandupdatetake a step'soutputConfig(the values and file roles passed to the next step; Step fields), andproject_writecreatetakessteps[].outputConfig. Whathandoff(the values and files passed between steps) means in the answers ofrun_read,execution_readandworkitem_readis in the field tables of getting a run, getting an execution result and getting a review request - 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_readreturns 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. Every tool in the project toolset 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). When this MCP server is connected to an agent in AGENTIC STAR chat, the agent is instructed to ask the user each time before calling it, showing what it will decide and how, and to call it only after the user approves (and not to call it in runs where it cannot ask the user). - Resend key: The
Idempotency-Keyheader of REST is passed as the argumentidempotencyKey - System integrations: Only the five operations marked with ✅ under "System integration" can be used. Other operations return an error regardless of scopes
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) |
Files of upload and update_content of project_file_write | Up to about 22 MB after decoding base64. Send a larger file (up to 512 MB) with REST |
Reading file content (get_file_content and get_content of project_file_read) | Over 5 MB, a download URL that takes the same token is returned instead of the content |
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 | About 30 seconds for simple tasks and 2 to 5 minutes for complex ones. Set the client timeout to 6 minutes or more. 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 invalid or expired |
403 Forbidden | The token has neither mcp:all nor mcp:connect. A missing scope for a tool is returned as a tool error (isError: true), not as HTTP 403. A request stopped by the front-end protection (WAF) also gets 403, with a JSON body (error.code is waf_blocked; error.reference holds the reference number when there is one) |
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) |
503 Service Unavailable | Authentication is temporarily unavailable. Please retry later. If the problem persists, contact the service administrator |
See Also
- AI Client Connection Guide (MCP) — Client configuration and how to connect
- Connection Methods Guide - MCP — Overview of connection methods
- Authentication API Reference (SaaS) — Token acquisition
- User API Reference — REST equivalents of the chat set
- Project API Reference — REST equivalents of the project set
- Model Context Protocol Specification — Protocol details