docs: document MCP OAuth support and simplify unreleased changelog

This commit is contained in:
yiling
2026-10-29 17:52:45 +08:00
parent 687b5a79d8
commit 5b7fc04b02
3 changed files with 128 additions and 23 deletions
+3 -8
View File
@@ -8,14 +8,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
### Added
* **mcp**: Shumai now has a built-in MCP server at `https://<your-shumai-host>/mcp`, supporting both OAuth 2.1 with Dynamic Client Registration and API token authentication, so external AI agents such as Claude Code, Cursor, or Kiro can browse projects and create, rename, move, or delete folders and files with your permissions. Like other MCP servers, it can also be served from its own host name, such as `https://mcp.example.com/mcp`
* **agent**: The built-in agent can now list the projects you have access to, so it can find a project's root folder on its own. Team owners can turn this off per agent like other tools
* **mcp**: External AI agents connected to Shumai's MCP server can now look at your files: images, video frames, PDF pages, 3D model views, and text files. Images are attached so the AI can see them, along with links that stay valid for about an hour. They can also get download links for files, as the web preview or the original upload
* **cli**: New `shumai-cli download` command saves files to your computer, up to 50 at a time: the smaller web preview by default, or the original upload with `--original`
* **cli**: New `shumai-cli read` command shows an image, video frames, PDF pages, a 3D model view, or the text of a file, and `--out` downloads the images into a folder. If rendering takes a while, `shumai-cli render <taskId>` picks up the result later
* **agent**: The built-in agent can now work more like a teammate: it can search for files by name, meaning, or metadata, read and post review comments (as you) and mark them resolved, set metadata such as a file's status, copy files, stack files into versions or take a version out of its stack, and read a folder's instructions for AI agents (AGENTS.md). Team owners can turn each of these off per agent
* **mcp**: External AI agents connected to Shumai's MCP server can do the same, and can now upload files and new versions: Shumai gives them a link to upload the file to, then creates the file once it's uploaded. They can also fill in a project's Creation Context fields (such as the prompt or model used) for the files they create
* **cli**: New `shumai-cli` commands to search files (`search`), copy them (`copy`), work with comments (`comment ls`, `comment add`, `comment resolve`), list and set metadata (`field ls`, `meta set`), manage versions (`version stack`, `version ls`, `version unstack`), and show a folder's instructions (`instructions`)
* **mcp**: Add a built-in MCP server supporting OAuth 2.1 and API tokens, allowing external AI agents (such as Claude Code, Cursor, or Kiro) to browse projects, manage and upload files, inspect media contents (images, video frames, PDF pages, 3D models, and text), search assets, manage review comments, update metadata, and organize version stacks
* **cli**: Add `shumai-cli` commands to download files (`download`), view and render media contents (`read`, `render`), search and copy files (`search`, `copy`), manage review comments (`comment`), view and update metadata (`field ls`, `meta set`), organize version stacks (`version`), and view folder instructions (`instructions`)
* **agent**: The built-in agent can now list accessible projects, search files by name, meaning, or metadata, read and post review comments, update metadata, copy files, stack and unstack versions, and read folder instructions (`AGENTS.md`), with configurable permissions per agent
### Fixed
+1 -1
View File
@@ -234,7 +234,7 @@ For more details on installation and usage, see the [CLI Readme](apps/cli/README
## MCP Server
Shumai includes a built-in MCP server at `/mcp`, so external agents such as Claude Code, Cursor, or Kiro can browse and organize your projects with an API token. See the [MCP server guide](docs/developer/mcp-server.mdx) for setup.
Shumai includes a built-in MCP server at `/mcp`, so external agents such as Claude Code, Cursor, or Kiro can browse and organize your projects with OAuth or an API token. See the [MCP server guide](docs/developer/mcp-server.mdx) for setup.
---
+124 -14
View File
@@ -14,44 +14,153 @@ Shumai includes a built-in [Model Context Protocol](https://modelcontextprotocol
## Connecting a Client
The server uses the Streamable HTTP transport at:
The MCP server uses the Streamable HTTP transport at:
```
https://<your-shumai-host>/mcp
```
It authenticates with an **API token**:
Shumai supports **OAuth 2.1** (recommended for seamless browser-based authentication) and **API tokens** (for headless environments or clients that do not support OAuth).
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.
Pick your client below to get started:
Then add the server to your client, sending the token as a Bearer header.
### Claude Code
**Claude Code**
[Claude Code](https://docs.anthropic.com/en/docs/claude-code) natively supports remote MCP servers with OAuth authentication. Add Shumai to your Claude Code configuration by running:
```bash
claude mcp add --transport http shumai https://<your-shumai-host>/mcp \
--header "Authorization: Bearer <your-api-token>"
claude mcp add shumai --transport http https://<your-shumai-host>/mcp
```
**Cursor, Kiro, and other clients with a JSON config**
When you start a new conversation, Claude Code will open a browser window for you to sign in and authorize access to your Shumai account. No manual API token is required.
Alternatively, you can manually configure `.claude/settings.json`:
```json
{
"mcpServers": {
"shumai": {
"type": "http",
"url": "https://<your-shumai-host>/mcp"
}
}
}
```
Or connect stdio via `mcp-remote`:
```bash
claude mcp add shumai -- npx -y mcp-remote https://<your-shumai-host>/mcp
```
### Cursor
Add Shumai to your Cursor MCP configuration (`~/.cursor/mcp.json` or project `.cursor/mcp.json`):
```json
{
"mcpServers": {
"shumai": {
"url": "https://<your-shumai-host>/mcp"
}
}
}
```
When Cursor connects to the server, it will prompt you in the browser to complete the OAuth sign-in and authorize access.
To authenticate with an API token instead, pass the `Authorization` header:
```json
{
"mcpServers": {
"shumai": {
"url": "https://<your-shumai-host>/mcp",
"headers": { "Authorization": "Bearer <your-api-token>" }
"headers": {
"Authorization": "Bearer <your-api-token>"
}
}
}
}
```
### Codex
```bash
codex mcp add shumai --url https://<your-shumai-host>/mcp
codex mcp login shumai
```
### VS Code
```bash
code --add-mcp '{"name":"shumai","type":"http","url":"https://<your-shumai-host>/mcp"}'
```
Start the server from your **MCP Servers** list in VS Code and sign in to Shumai when prompted.
### Other Clients
**Remote (HTTP)**
If your client natively supports remote HTTP MCP servers:
```json
{
"mcpServers": {
"shumai": {
"url": "https://<your-shumai-host>/mcp"
}
}
}
```
**Local Bridge (`mcp-remote` / stdio)**
For clients that only support local (stdio) MCP servers, use `mcp-remote` to connect to Shumai's remote HTTP endpoint:
```json
{
"mcpServers": {
"shumai": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://<your-shumai-host>/mcp"]
}
}
}
```
---
## Authentication
Shumai's MCP server supports two authentication methods:
### OAuth 2.1 (Recommended)
Shumai implements OAuth 2.1 with Dynamic Client Registration ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)) and OAuth Protected Resource Metadata ([RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728) / [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414)).
- **Seamless Sign-in**: Supported MCP clients automatically discover authorization endpoints and complete the OAuth handshake in your browser.
- **Access Control**: External agents act with your permissions in Shumai. Actions are attributed to your user account and logged in the team audit log with `via: mcp`.
- **Clearing OAuth Cache**: If you need to re-authenticate or clear stored credentials in CLI tools such as `mcp-remote` or Claude Code, remove the local authentication cache:
```bash
rm -rf ~/.mcp-auth
```
### API Tokens
API tokens are ideal for automated CI/CD pipelines, headless environments, or clients that do not support interactive OAuth.
1. In Shumai, open **Team Settings** → **API Tokens**.
2. Enter a name (for example, `ci-agent` or `cursor-token`) and click **Generate**.
3. Copy the token from the dialog. It is only shown once.
4. Pass the token in the `Authorization: Bearer <your-api-token>` header (or `x-api-key` header).
<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**.
password, use a separate token per client, and revoke tokens you no longer use from **Team
Settings** → **API Tokens**.
</Warning>
---
@@ -108,5 +217,6 @@ Every call runs with your permissions: for example, a **Reviewer** can list asse
## Troubleshooting
- **401 Unauthorized**: The token is missing, mistyped, or revoked. Generate a new token and update your client configuration.
- **OAuth Authorization Expired or Invalid**: Clear your client's local OAuth session cache (`rm -rf ~/.mcp-auth`) and restart your MCP client to re-authenticate.
- **401 Unauthorized**: The API token or OAuth access token is missing, expired, mistyped, or revoked. For API tokens, generate a new token under **Team Settings** → **API Tokens** and update your client configuration.
- **Permission errors on a tool call**: Your role in that team or project does not allow the action.