mirror of
https://github.com/shumaiOne/shumai.git
synced 2026-11-22 18:48:44 +00:00
Enable the mcp and cli surfaces for read_asset and get_asset_render. - MCP: add per-Operation tool extensions. The read presenter attaches up to 8 images (2 MB each) inline, lists image links, supports inlineImages: false, and tells the model to call get_asset_render when a render is pending. Storage keys are stripped from the result. - CLI: generated commands can flatten object inputs into prefixed flags (cli.flatten) and omit fields (cli.omit); add per-command extensions. New `read` and `render` commands print image links, download them with --out, and support --no-wait with a printed `render <taskId>` hint. - Round frame timestamps in labels to 3 decimals.
86 lines
4.0 KiB
Plaintext
86 lines
4.0 KiB
Plaintext
---
|
|
title: Shumai MCP Server
|
|
description: Let external AI agents such as Claude Code, Cursor, or Kiro work with your Shumai projects.
|
|
---
|
|
|
|
Shumai includes a built-in [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server. Any MCP-compatible agent can connect to it and browse projects, look at images, videos, and documents, create folders, and organize assets on your behalf, using the same tools as Shumai's built-in agent.
|
|
|
|
<Note>
|
|
This page is about connecting **external agents to Shumai**. To connect Shumai's own agents to
|
|
other tools, see [MCP Servers](/using-shumai/mcp-servers).
|
|
</Note>
|
|
|
|
---
|
|
|
|
## Connecting a Client
|
|
|
|
The server uses the Streamable HTTP transport at:
|
|
|
|
```
|
|
https://<your-shumai-host>/api/mcp
|
|
```
|
|
|
|
It authenticates with an **API token**:
|
|
|
|
1. In Shumai, open **Team Settings** → **API Tokens**.
|
|
2. Enter a name (for example, `claude-code`) and click **Generate**.
|
|
3. Copy the token from the dialog. It is only shown once.
|
|
|
|
Then add the server to your client, sending the token as a Bearer header.
|
|
|
|
**Claude Code**
|
|
|
|
```bash
|
|
claude mcp add --transport http shumai https://<your-shumai-host>/api/mcp \
|
|
--header "Authorization: Bearer <your-api-token>"
|
|
```
|
|
|
|
**Cursor, Kiro, and other clients with a JSON config**
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"shumai": {
|
|
"url": "https://<your-shumai-host>/api/mcp",
|
|
"headers": { "Authorization": "Bearer <your-api-token>" }
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
<Warning>
|
|
An API token acts as you: the agent can do anything your account can do in Shumai. Store it like a
|
|
password, use a separate token per client, and revoke tokens you no longer use from **API
|
|
Tokens**.
|
|
</Warning>
|
|
|
|
---
|
|
|
|
## Available Tools
|
|
|
|
| Tool | What it does |
|
|
| ------------------ | ----------------------------------------------------------------------------------------------------- |
|
|
| `list_projects` | Lists the projects you can access, with each project's root folder. |
|
|
| `list_assets` | Lists files and folders in a folder, page by page. |
|
|
| `create_folder` | Creates a folder. |
|
|
| `rename_asset` | Renames a file or folder. |
|
|
| `move_assets` | Moves files or folders into another folder. |
|
|
| `delete_asset` | Moves a file or folder to the project trash. Marked as destructive so clients can ask you to confirm. |
|
|
| `read_asset` | Looks at a file: an image, video frames, PDF pages, a 3D model view, or the text of a text file. |
|
|
| `get_asset_render` | Gets the result of a `read_asset` call that was still rendering. |
|
|
|
|
### Reading Files
|
|
|
|
`read_asset` attaches the images to the result so the AI model can see them: up to 8 images per call, each up to 2 MB. Any other images are listed as links only. Every result also includes a link to each image, valid for about an hour. Pass `inlineImages: false` to get links only, for example when your client can't show images.
|
|
|
|
Rendering video frames or PDF pages can take a while. If it takes longer than about 20 seconds, `read_asset` returns `status: "pending"` with a `taskId`, and the model calls `get_asset_render` with that `taskId` to get the result. Only the user who started the read can get its result.
|
|
|
|
Every call runs with your permissions: for example, a **Reviewer** can list assets but cannot create or rename them. Actions are recorded in the team audit log and attributed to you, marked as coming from MCP.
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
- **401 Unauthorized**: The token is missing, mistyped, or revoked. Generate a new token and update your client configuration.
|
|
- **Permission errors on a tool call**: Your role in that team or project does not allow the action.
|