Skip to main content

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.

SaaS Edition

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.

SaaS
https://api.fd.agenticstar.tm.softbank.jp

Endpoint​

SaaS
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 token needs one of the following scopes. A token with neither gets 403 Forbidden.

ScopePurpose
mcp:allUse all MCP tools. No other scope is needed
mcp:connectConnect 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)
Use mcp:connect for new apps

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

More tools are available to apps with mcp:all

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

QueryAvailable tools
None, or ?toolsets=chatThe chat set (6 tools)
?toolsets=projectThe project set (27 tools)
?toolsets=chat,projectBoth (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 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 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.

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. "Required scope" is not checked for a token with mcp:all. A token with mcp:connect also needs that scope.

Chat Set​

ToolDescriptionRequired scope (with mcp:connect)
execute_chatSend a task to an agent and get the resultchat:exec (plus chat:file when attaching files)
get_file_contentGet a deliverable filechat:exec
get_ui_resourceGet the HTML of a UI resourcechat:exec
cancel_chatCancel a running taskchat:exec
list_personasGet the list of personasNone (mcp:connect alone is enough)
list_conversation_messagesRead the messages of your conversationchat: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.

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

UI HTML can be large

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.

ToolPurposemethodREST equivalentRequired scope (with mcp:connect)System integration
project_readRead projectslistGET /v1/projectsproject:read✅
list_sharedGET /v1/projects/sharedproject:read
getGET /v1/projects/{projectId}project:read
get_controlGET /v1/projects/{projectId}/controlproject:read
list_organizationsGET /v1/projects/organizationsproject:read
list_automation_destinationsGET /v1/projects/automation-destinationsproject:read
export_definitionGET /v1/projects/{projectId}/definitionproject:read
get_definition_approvalGET /v1/projects/{projectId}/definition-approvalproject:read
project_status_readRead the queue, KPI, and records (audit trail)list_my_queueGET /v1/queueproject:read
list_queueGET /v1/projects/{projectId}/queueproject:read
get_kpiGET /v1/projects/{projectId}/kpiproject:read
get_kpi_trendsGET /v1/projects/{projectId}/kpi/trendsproject:read
list_audit_eventsGET /v1/projects/{projectId}/auditproject:read
project_file_readRead the project library and the content of fileslistGET /v1/projects/{projectId}/libraryproject:read
list_versionsGET /v1/projects/{projectId}/library/{fileId}/versionsproject:read
get_contentGET /v1/projects/{projectId}/files/contentproject:read
placement_readRead agent placementslistGET /v1/projects/{projectId}/placementsproject:read
getGET /v1/projects/{projectId}/placements/{placementId}project:read
get_memory_candidatesGET /v1/projects/{projectId}/memory-candidatesproject:read
run_readRead workflow runslistGET /v1/projects/{projectId}/runsproject:read
getGET /v1/projects/{projectId}/runs/{runId}project:read✅
get_configGET /v1/projects/{projectId}/runs/{runId}/configproject:read
get_resume_optionsGET /v1/projects/{projectId}/runs/{runId}/resumeproject:read
execution_readRead agent executionslistGET /v1/projects/{projectId}/executionsproject:read
getGET /v1/projects/{projectId}/executions/{executionId}project:read
list_operationsGET /v1/projects/{projectId}/executions/{executionId}/operationsproject:read
get_timelineGET /v1/projects/{projectId}/executions/{executionId}/timelineproject:read
workitem_readRead work items (approval requests)listGET /v1/workitemsproject:read
getGET /v1/workitems/{workItemId}project:read
connector_readRead connections (MCP servers, A2A agents)get_mcpGET /v1/connectors/mcp/{connectionId}project:read
get_a2aGET /v1/connectors/a2a/{connectionId}project:read
webhook_readRead project webhooks and their deliverieslistGET /v1/projects/{projectId}/webhooksproject:read
list_deliveriesGET /v1/projects/{projectId}/webhooks/{webhookId}/deliveriesproject:read
agent_readRead Agents in the librarylistGET /v1/agentsassets:read
list_sharedGET /v1/agents/sharedassets:read
getGET /v1/agents/{agentId}assets:read
playbook_readRead Playbooks in the librarylistGET /v1/playbooksassets:read or chat:exec
list_sharedGET /v1/playbooks/sharedassets:read or chat:exec
getGET /v1/playbooks/{playbookId}assets:read
skill_readRead Skills in the librarylistGET /v1/skillsassets:read or chat:exec
list_sharedGET /v1/skills/sharedassets:read or chat:exec
getGET /v1/skills/{skillId}assets:read
list_versionsGET /v1/skills/{skillId}/versionsassets:read
list_filesGET /v1/skills/{skillId}/filesassets:read
get_fileGET /v1/skills/{skillId}/files/contentassets:read
project_writeCreate or change projectscreatePOST /v1/projectsproject:write
updatePATCH /v1/projects/{projectId}project:write
importPOST /v1/projects/importproject:write
dismiss_relinkDELETE /v1/projects/{projectId}/relinkproject:write
withdraw_definitionDELETE /v1/projects/{projectId}/definition-approvalproject:write
project_file_writeAdd, change, and delete files in the project libraryuploadPOST /v1/projects/{projectId}/libraryproject:write
copyPOST /v1/projects/{projectId}/library/copyproject:write
update_contentPUT /v1/projects/{projectId}/library/{fileId}/contentproject:write
restorePOST /v1/projects/{projectId}/library/{fileId}/restoreproject:write
import_latestPOST /v1/projects/{projectId}/library/{fileId}/import-latestproject:write
deleteDELETE /v1/projects/{projectId}/library/{fileId}project:write
step_writeAdd, change, reorder, or delete stepscreatePOST /v1/projects/{projectId}/stepsproject:write
updatePATCH /v1/projects/{projectId}/steps/{stepId}project:write
reorderPUT /v1/projects/{projectId}/steps/orderproject:write
deleteDELETE /v1/projects/{projectId}/steps/{stepId}project:write
placement_writePlace agents, change placements, and bind files to stepscreatePOST /v1/projects/{projectId}/placementsproject:write
deleteDELETE /v1/projects/{projectId}/placements/{placementId}project:write
update_stepsPUT /v1/projects/{projectId}/placements/{placementId}/stepsproject:write
update_memoryPATCH /v1/projects/{projectId}/placements/{placementId}/memoryproject:write
update_instructionPATCH /v1/projects/{projectId}/placements/{placementId}/instructionproject:write
update_schedulePATCH /v1/projects/{projectId}/placements/{placementId}/scheduleproject:write
update_library_bindingsPUT /v1/projects/{projectId}/placements/{placementId}/library-bindingsproject:write
trigger_writeCreate, change, and delete triggerscreatePOST /v1/projects/{projectId}/triggersproject:write
updatePATCH /v1/projects/{projectId}/triggers/{triggerId}project:write
deleteDELETE /v1/projects/{projectId}/triggers/{triggerId}project:write
webhook_writeCreate, change, and delete project webhooks (secret is not returned)createPOST /v1/projects/{projectId}/webhooksproject:write
updatePATCH /v1/projects/{projectId}/webhooks/{webhookId}project:write
deleteDELETE /v1/projects/{projectId}/webhooks/{webhookId}project:write
project_runStart 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 runstart_runPOST /v1/projects/{projectId}/runsproject:run✅
fire_triggerPOST /v1/projects/{projectId}/triggers/{triggerId}/fireproject:run✅
rerun_executionPOST /v1/projects/{projectId}/executions/{executionId}/rerunproject:run
reassign_approversPUT /v1/projects/{projectId}/runs/{runId}/approversproject:write
set_deadlinePATCH /v1/projects/{projectId}/runs/{runId}project:write
resume_runPOST /v1/projects/{projectId}/runs/{runId}/resumeproject:run
cancel_runPOST /v1/projects/{projectId}/runs/{runId}/cancelproject:run✅
project_deleteDelete a project—DELETE /v1/projects/{projectId}project:delete
workitem_decideDecide a work item or extend its due datedecide (optional)POST /v1/workitems/{workItemId}/decisionproject:decide
extendPATCH /v1/workitems/{workItemId}project:decide
agent_writeCreate, change, or copy AgentscreatePOST /v1/agentsassets:write
updatePATCH /v1/agents/{agentId}assets:write
copyPOST /v1/agents/{agentId}/copyassets:write
playbook_writeCreate, change, or copy PlaybookscreatePOST /v1/playbooksassets:write
updatePATCH /v1/playbooks/{playbookId}assets:write
copyPOST /v1/playbooks/{playbookId}/copyassets:write
skill_writeCreate Skills, change their files and settings, or copy themcreatePOST /v1/skillsassets:write
replace_filesPUT /v1/skills/{skillId}/filesassets:write
edit_filesPATCH /v1/skills/{skillId}/filesassets:write
update_settingsPATCH /v1/skills/{skillId}assets:write
copyPOST /v1/skills/{skillId}/copyassets:write
agent_deleteDelete an Agent—DELETE /v1/agents/{agentId}assets:delete
playbook_deleteDelete a Playbook—DELETE /v1/playbooks/{playbookId}assets:delete
skill_deleteDelete 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 in body). Their names and meanings are in the input schema of each tool returned by tools/list. Exceptions: upload and update_content of project_file_write send the file not as multipart/form-data but as the arguments content (the content) and encoding (utf-8 or base64; the default is utf-8). upload also sends filename (the name in the library). method of workitem_decide can be omitted (it then means decide). 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 (delete of step_write, delete of placement_write, delete of trigger_write, delete of webhook_write, rerun_execution of project_run, copy of agent_write and playbook_write, and upload, update_content, and delete of project_file_write) do not use them 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. create and update of step_write accept the argument automationConfig (settings of external automation). defaultZone also accepts "branch", and update also accepts the argument branchConfig (settings of a branch).
  • Values and files for the next step: step_write create and update take a step's outputConfig (the values and file roles passed to the next step; Step fields), and project_write create takes steps[].outputConfig. What handoff (the values and files passed between steps) means in the answers of run_read, execution_read and workitem_read is 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_content of project_file_read returns 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. Every tool in the project toolset 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). 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-Key header of REST is passed as the argument idempotencyKey
  • 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.

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)
Files of upload and update_content of project_file_writeUp 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 conversationOne at a time. Sending while the previous call is running returns an error (CONVERSATION_BUSY)
Time taken by execute_chatAbout 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 StatusDescription
400 Bad RequestFor example, the value of the MCP-Protocol-Version header is not in Supported Protocol Versions
401 UnauthorizedAccess token invalid or expired
403 ForbiddenThe 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 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)
503 Service UnavailableAuthentication is temporarily unavailable. Please retry later. If the problem persists, contact the service administrator

See Also​