MCP API Reference (SaaS)

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 via tool calls.

SaaS Edition Only

The endpoints in this reference are available only in the SaaS edition. On the Marketplace edition, MCP is disabled at build time and the endpoint does not exist.

For a connection-method overview (including configuration examples), see the Connection Methods Guide.

Endpoint

SaaS

Method	Endpoint	Description
POST	/api/v1/mcp	MCP JSON-RPC endpoint (Streamable HTTP, Stateless mode)

Base URL: https://api.fd.agenticstar.tm.softbank.jp

Protocol: JSON-RPC 2.0 over Streamable HTTP

Mode: Stateless (a server instance is created and destroyed per request)

Authentication

All requests must include the Authorization: Bearer <access_token> header. The token requires the following scopes:

Scope	Purpose
mcp:exec	Required to use MCP at all
mcp:file	Additionally required when attaching files via execute_chat

For token acquisition, see the Authentication API Reference (SaaS).

Request Headers

Header	Required	Description
Authorization	✅	Bearer <access_token>
Content-Type	✅	application/json
MCP-Protocol-Version	—	MCP protocol version supported by the client (recommended)

JSON-RPC Methods

MCP uses standard JSON-RPC 2.0. The endpoint supports the following standard methods:

Method	Description
initialize	Capability negotiation between client and server
tools/list	Get the list of available tools
tools/call	Invoke a tool
resources/list	Get the list of available resources
resources/read	Read a resource

For details, see the Model Context Protocol specification.

Provided Tools

The tools available via tools/call:

execute_chat

Send a task to an agent and retrieve the execution result (response text, deliverable files, execution trace).

Item	Details
Required scope	mcp:exec (and mcp:file when attaching files)
Key input	prompt (required), conversationId (optional, to continue a conversation), files (optional, base64-encoded)
Key output	response, conversationId, deliverables[] (metadata of generated files), executionSteps[]

When deliverables[].size exceeds fileSizeLimitMB (environment-dependent, default 20 MB), get_file_content returns a download link instead of the inline content.

get_file_content

Retrieve files listed in the deliverables[] or executionSteps[].files[] of execute_chat.

Item	Details
Required scope	mcp:exec
Key input	filepath (required)
Key output	File metadata + content (inline for small files, download link for large files)

cancel_chat

Cancel a running task.

Item	Details
Required scope	mcp:exec
Key input	conversationId (required)
Key output	Cancellation result

list_personas

Retrieve the list of applicable personas (response personalities).

Item	Details
Required scope	mcp:exec
Key input	None
Key output	Persona list (key, name, description)

Request Examples

initialize

curl

curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/mcp \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2024-11-05" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": { "name": "my-client", "version": "1.0.0" }
    }
  }'

tools/call (execute_chat)

curl

curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/mcp \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "execute_chat",
      "arguments": {
        "prompt": "Please analyze the sales data"
      }
    }
  }'

Error Codes

Standard JSON-RPC 2.0 error codes are used.

code	Description
-32700	Parse Error (failed to parse request)
-32600	Invalid Request (malformed JSON-RPC request)
-32601	Method Not Found (unsupported method)
-32602	Invalid Params (parameter error)
-32603	Internal Error (server-side error)

HTTP-layer errors:

HTTP Status	Description
401 Unauthorized	Access token invalid or expired
403 Forbidden	Required scope missing (mcp:exec / mcp:file)
413 Payload Too Large	Request body exceeds the size limit

See Also

• Connection Methods Guide - MCP — Configuration examples and use cases
• Authentication API Reference (SaaS) — Token acquisition
• User API Reference — REST equivalents