# 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](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/build/reference/helm-values-ref.md) in the Build section.
>
> For client configuration and how to connect, see [AI Client Connection Guide (MCP)](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/guide/ai-client-guide.md). For a connection-method overview, see the [Connection Methods Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/guide/connection-guide.md#mcpmodel-context-protocol).

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

| 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 following two kinds of tokens can be used. The Marketplace edition applies no scope restrictions.

| Token                                                          | How to get it                                                                                                                                                      | Available tools                                                                                                                                                                                    |
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A user token of an application (sign-in from an external tool) | Sign in with the AI client ([AI Client Connection Guide (MCP)](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/guide/ai-client-guide.md)) | 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) token                   | Client Credentials flow ([Authentication Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/guide/auth-guide.md))                     | 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](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/guide/setup-guide.md))
- 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](https://modelcontextprotocol.io/specification/2025-11-25/basic/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](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/guide/setup-guide.md))

## 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 (5 tools)                                                    |
| `?toolsets=project`                | The project set (14 tools)                                                |
| `?toolsets=published`              | The published set (one tool per published project, and `get_project_run`) |
| `?toolsets=chat,project,published` | All 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.

| 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](#tool-sets-toolsets).

### Chat Set

| Tool                         | Description                                                   |
| ---------------------------- | ------------------------------------------------------------- |
| `execute_chat`               | Send a task to a registered Agent and get the result          |
| `get_file_content`           | Get a deliverable file                                        |
| `cancel_chat`                | Cancel a running task                                         |
| `list_agents`                | Get the list of registered Agents that `execute_chat` can run |
| `list_conversation_messages` | Read 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)](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/reference/user-api-reference-projects.md) (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                                                    | System integration |
| --------------------- | ------------------------------------------------------------------------------------------- | ----------------------- | ------------------------------------------------------------------ | ------------------ |
| `project_read`        | Read projects                                                                               | `list`                  | `GET /v1/projects`                                                 | ✅                  |
|                       |                                                                                             | `list_shared`           | `GET /v1/projects/shared`                                          |                    |
|                       |                                                                                             | `get`                   | `GET /v1/projects/{projectId}`                                     |                    |
|                       |                                                                                             | `get_control`           | `GET /v1/projects/{projectId}/control`                             |                    |
|                       |                                                                                             | `list_organizations`    | `GET /v1/projects/organizations`                                   |                    |
| `project_status_read` | Read the queue, KPIs, and records (audit trail)                                             | `list_my_queue`         | `GET /v1/queue`                                                    |                    |
|                       |                                                                                             | `list_queue`            | `GET /v1/projects/{projectId}/queue`                               |                    |
|                       |                                                                                             | `get_kpi`               | `GET /v1/projects/{projectId}/kpi`                                 |                    |
|                       |                                                                                             | `list_audit_events`     | `GET /v1/projects/{projectId}/audit`                               |                    |
| `project_file_read`   | Read the content of a file                                                                  | `get_content`           | `GET /v1/projects/{projectId}/files/content`                       |                    |
| `placement_read`      | Read agent placements and the registered Agents that can be placed                          | `list`                  | `GET /v1/projects/{projectId}/placements`                          |                    |
|                       |                                                                                             | `get`                   | `GET /v1/projects/{projectId}/placements/{placementId}`            |                    |
|                       |                                                                                             | `list_agent_candidates` | `GET /v1/projects/agent-candidates`                                |                    |
| `run_read`            | Read workflow runs and their artifacts                                                      | `list`                  | `GET /v1/projects/{projectId}/runs`                                |                    |
|                       |                                                                                             | `get`                   | `GET /v1/projects/{projectId}/runs/{runId}`                        | ✅                  |
|                       |                                                                                             | `get_config`            | `GET /v1/projects/{projectId}/runs/{runId}/config`                 |                    |
|                       |                                                                                             | `list_artifacts`        | `GET /v1/projects/{projectId}/artifacts`                           |                    |
|                       |                                                                                             | `get_artifact_content`  | `GET /v1/projects/{projectId}/artifacts/{artifactId}/content`      |                    |
| `execution_read`      | Read agent executions                                                                       | `list`                  | `GET /v1/projects/{projectId}/executions`                          |                    |
|                       |                                                                                             | `get`                   | `GET /v1/projects/{projectId}/executions/{executionId}`            |                    |
|                       |                                                                                             | `list_operations`       | `GET /v1/projects/{projectId}/executions/{executionId}/operations` |                    |
|                       |                                                                                             | `get_timeline`          | `GET /v1/projects/{projectId}/executions/{executionId}/timeline`   |                    |
| `workitem_read`       | Read work items                                                                             | `list`                  | `GET /v1/workitems`                                                |                    |
|                       |                                                                                             | `get`                   | `GET /v1/workitems/{workItemId}`                                   |                    |
| `connector_read`      | Read connectors (MCP servers and A2A agents)                                                | `get_mcp`               | `GET /v1/connectors/mcp/{connectionId}`                            |                    |
|                       |                                                                                             | `get_a2a`               | `GET /v1/connectors/a2a/{connectionId}`                            |                    |
| `project_write`       | Create and change projects                                                                  | `create`                | `POST /v1/projects`                                                |                    |
|                       |                                                                                             | `update`                | `PATCH /v1/projects/{projectId}`                                   |                    |
| `step_write`          | Add, change, reorder, and delete steps                                                      | `create`                | `POST /v1/projects/{projectId}/steps`                              |                    |
|                       |                                                                                             | `update`                | `PATCH /v1/projects/{projectId}/steps/{stepId}`                    |                    |
|                       |                                                                                             | `reorder`               | `PUT /v1/projects/{projectId}/steps/order`                         |                    |
|                       |                                                                                             | `delete`                | `DELETE /v1/projects/{projectId}/steps/{stepId}`                   |                    |
| `placement_write`     | Place registered Agents and change placements                                               | `create`                | `POST /v1/projects/{projectId}/placements`                         |                    |
|                       |                                                                                             | `delete`                | `DELETE /v1/projects/{projectId}/placements/{placementId}`         |                    |
|                       |                                                                                             | `update_steps`          | `PUT /v1/projects/{projectId}/placements/{placementId}/steps`      |                    |
|                       |                                                                                             | `update_schedule`       | `PATCH /v1/projects/{projectId}/placements/{placementId}/schedule` |                    |
| `project_run`         | Start workflow runs, fire triggers, and change the reviewers and deadline of a workflow run | `start_run`             | `POST /v1/projects/{projectId}/runs`                               | ✅                  |
|                       |                                                                                             | `fire_trigger`          | `POST /v1/projects/{projectId}/triggers/{triggerId}/fire`          | ✅                  |
|                       |                                                                                             | `reassign_approvers`    | `PUT /v1/projects/{projectId}/runs/{runId}/approvers`              |                    |
|                       |                                                                                             | `set_deadline`          | `PATCH /v1/projects/{projectId}/runs/{runId}`                      |                    |
| `project_delete`      | Delete a project                                                                            | —                       | `DELETE /v1/projects/{projectId}`                                  |                    |
| `workitem_decide`     | Decide work items and extend their due dates                                                | `decide` (optional)     | `POST /v1/workitems/{workItemId}/decision`                         |                    |
|                       |                                                                                             | `extend`                | `PATCH /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.

| Tool              | Description                                                                                                                                                                         |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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_run` | Reads 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 offered                                                   | REST                                                                                                                                                                                                                                                                                                    | MCP                           |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
| Conversations with Agents                                         | Chat API (`POST /v1/chat/completions`)                                                                                                                                                                                                                                                                  | The chat set (`execute_chat`) |
| Project features (create, change, run, read)                      | [User API Reference (Projects)](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/reference/user-api-reference-projects.md) and [System Integration API Reference](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/reference/api-reference.md#projects) | The 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.

| 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)                                                                                                                                                                                                                                                              |
| 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 conversation                                                                                   | One at a time. Sending while the previous call is running returns an error (`CONVERSATION_BUSY`)                                                                                                                                                                                                                                         |
| Time taken by `execute_chat`                                                                                              | It 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](#provided-tools)).

| HTTP Status              | Description                                                                                                                         |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `400 Bad Request`        | For example, the value of the `MCP-Protocol-Version` header is not in [Supported Protocol Versions](#supported-protocol-versions)   |
| `401 Unauthorized`       | Access token missing, invalid, or expired                                                                                           |
| `404 Not Found`          | The 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 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](#limits))                                                                              |

## See Also

- [AI Client Connection Guide (MCP)](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/guide/ai-client-guide.md) — Client configuration and how to connect
- [Connection Methods Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/guide/connection-guide.md) — Overview of connection methods
- [Authentication API Reference](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/reference/auth-mp-ref.md) — Token acquisition
- [User API Reference (Conversations, Organizations)](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/reference/user-api-reference.md) — REST equivalents of the chat set
- [User API Reference (Projects)](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/reference/user-api-reference-projects.md) — REST equivalents of the project set
- [Model Context Protocol Specification](https://modelcontextprotocol.io/specification) — Protocol details
