Sorb MCP

Sorb MCP connects external Agents to Sorb projects, models, resources and tasks. You can use browser OAuth with the remote MCP service, or a personal access token (PAT) with the original local tools.

The package provides 38 tools for discovery, task creation and estimation, status and output queries, task operations, and bounded local file upload/download. Tasks retain Sorb's existing project permissions, billing, confirmation, idempotency and audit behavior. Canvas operations are outside this package's scope.

Requires Python 3.13. A Sorb account and access to a running Sorb server are required. This package does not contain the Sorb backend or any model Provider credentials.

Browser login (0.2.0)

Requires a Sorb server with remote MCP enabled and the official public client sorb-mcp-cli registered (included in the corresponding Sorb release). Install uv, then run on your desktop:

uvx --python 3.13 --from sorb-mcp==0.2.0 sorb-mcp login
uvx --python 3.13 --from sorb-mcp==0.2.0 sorb-mcp check

The first command opens your browser for Sorb login and consent. The second verifies tool discovery and queries visible projects without creating tasks. Add this to your Agent's MCP configuration:

{
  "mcpServers": {
    "sorb": {
      "command": "uvx",
      "args": ["--python", "3.13", "--from", "sorb-mcp==0.2.0", "sorb-mcp", "remote"]
    }
  }
}

Refresh or restart the client to load the configuration. No token belongs in the config. The bridge exposes the remote server's 36 tools, uses the current upstream MCP protocol, and adapts local stdio clients through the official SDK. Remote project selection requires explicit project IDs in subsequent calls; remote tools do not perform local file upload or download.

Credentials are stored per Sorb address in ~/.config/sorb/mcp/, with private directory/file permissions on macOS/Linux. A durable SQLite refresh claim coordinates client processes; each refresh token is sent at most once. New credentials persist before the claim is cleared. A lost response or crashed refresh requires login. On Windows, protect the account directory with its user ACL. Revoke OAuth grants in the Sorb MCP panel. If a refresh response is lost, log in again rather than replaying a refresh token.

Login requests read permissions by default. For a task creation workflow, request the needed scopes explicitly, for example:

uvx --python 3.13 --from sorb-mcp==0.2.0 sorb-mcp login --scopes 'projects:read models:read resources:read voices:read tasks:read tasks:create'

The user still confirms the permissions on Sorb's page. An insufficient-scope response asks you to log in again with the necessary scopes; the bridge does not automatically expand consent. To use a different Sorb server, pass --base-url https://your-sorb-host to each command or set SORB_BASE_URL consistently. OAuth is only sent to the upstream HTTP MCP endpoint; the downstream stdio client receives no credentials. No DCR or public metadata hosting is needed for the official pre-registered client.

Access token connection

Install uv. The MCP client can then launch a pinned version directly from PyPI:

uvx --python 3.13 --from sorb-mcp==0.1.1 sorb-mcp

Or install the command in a Python 3.13 environment:

python -m pip install sorb-mcp==0.1.1

In Sorb, open 个人中心 → 用户信息 → MCP → 访问令牌 (Personal Center → User Information → MCP → Access Tokens). Create a token with the operations you need. Start with the default read scopes to verify the connection. The token is displayed only once.

For clients using the mcpServers configuration format:

{
  "mcpServers": {
    "sorb": {
      "command": "uvx",
      "args": ["--python", "3.13", "--from", "sorb-mcp==0.1.1", "sorb-mcp"],
      "env": {
        "SORB_PAT": "<your personal access token>"
      }
    }
  }
}

The tool defaults to https://sorb.huche.games; only SORB_PAT is required for this Sorb service. To connect to a self-hosted or local instance, optionally set SORB_BASE_URL to its root URL, without /api or /api/mcp. Remote servers must use HTTPS; HTTP is permitted only for loopback development addresses. If the client cannot find uvx, set command to its actual executable path. Store the PAT in your client's secure configuration, never in chat messages or shared files.

After restarting or refreshing the client, ask the Agent to list your visible projects using sorb_list_projects. Successful tool output verifies the connection. Use sorb_select_project, sorb_list_models, sorb_get_model_schema and sorb_get_task_capabilities before requesting generation. Query operations do not create Sorb tasks; generation can incur the existing Sorb model fees.

Local files

Local upload/download requires explicitly configured, existing absolute directories:

{
  "SORB_INPUT_DIRS": "/absolute/path/references",
  "SORB_OUTPUT_DIRS": "/absolute/path/outputs"
}

Add these keys to the client's env only when needed. Multiple directories use the operating system's path separator (: on macOS/Linux, ; on Windows). Client roots may further narrow these directories. Downloads do not overwrite existing files; symlink traversal is rejected. Transfer limits default to 512 MiB and 120 seconds, and Sorb's server-side upload limits still apply.

Optional settings: SORB_CA_FILE for a trusted private CA, SORB_TIMEOUT_SECONDS (default 60), SORB_MAX_TRANSFER_BYTES, and SORB_TRANSFER_TIMEOUT_SECONDS. TLS verification remains enabled.

Permissions and retries

• Each operation rechecks the token scopes and current user/project permissions. Read-only projects cannot create tasks.
• Keep the same client_namespace and idempotency_key for one logical write. After a timeout, query sorb_get_submission with the original identity instead of generating a new key and repeating the task.
• Tasks requiring human preview or confirmation return a Sorb user-action link. The Agent prepares the proposal and queries its state; the user confirms in Sorb.
• Revoke or replace a PAT in the MCP panel. Revocation prevents subsequent calls but does not cancel tasks already accepted by Sorb.

Remote OAuth alternative

Compatible clients can connect directly to https://<your Sorb host>/api/mcp over Streamable HTTP and OAuth without installing this package. The remote endpoint uses MCP 2026-07-28 and supports CIMD or administrator pre-registered public clients, without a DCR endpoint. OAuth tokens are distinct from PATs; do not put a PAT into the remote OAuth connection.

Remote client compatibility must be verified by an authenticated tool call. This package also provides the optional OAuth login and stdio bridge described above; it does not configure or enable the remote Sorb server.

For the Chinese installation guide, configuration examples and troubleshooting, open 个人中心 → 用户信息 → MCP → 接入帮助 on your Sorb server. The guide can also be downloaded as Markdown.