unfoldx-mcp
A stdio MCP server that exposes the UnfoldX public API (unfoldx.v2) as MCP tools.
It reuses the unfoldx CLI's API client and credential store. Log in once with the
CLI (unfoldx login); the server reads that credential for the same API base on
every call, so it picks up a new login without a restart. It never prints the token.
uv tool install unfoldx-mcp # or: pip install unfoldx-mcp
unfoldx login # approve in the browser
claude mcp add unfoldx -- unfoldx-mcp # any MCP host that launches stdio servers
codex mcp add unfoldx -- unfoldx-mcp # Codex
qwen mcp add -s user unfoldx unfoldx-mcp
gemini mcp add -s user unfoldx unfoldx-mcp # without -s user it writes the project's .gemini/settings.json
Kimi Code reads ~/.kimi-code/mcp.json (mcpServers, the same JSON as Cursor). DeepSeek Harness (dsh)
mounts MCP servers as @deepseek-ai/dsh-mcp-client rows in ~/.dsh/cordis.patch.yml
(- insert: [{id: mcp-unfoldx, name: '@deepseek-ai/dsh-mcp-client', config: {serverName: unfoldx, transport: stdio, command: unfoldx-mcp}}]).
To check a host, ask it to call unfoldx_whoami; it should name your credential.
Every run and workspace carries web_url; give it to the user so they can watch the run on the web.
Every tool is a short call and returns the same envelope as the HTTP API and
unfoldx --json, as both structuredContent and JSON text:
{"schema":"unfoldx.v2","ok":true,"data":…}. Business failures (not logged in,
missing scope, not found, …) come back with isError: true and
{"ok":false,"error":{type,code,message,retryable,…}}. A run waiting for an answer
is a normal state, not an error; its question carries approval_url for the user.
unfoldx_run_submit requires a command_id chosen and saved before the call
(8–128 letters, digits, ., _, :, -). Reuse it verbatim when retrying. On a lost
response, query unfoldx_command_get with that id; never generate a replacement id to retry.
Read each card’s answer_schema and answer_examples before answering. Each tool advertises
and validates its actual response schema from unfoldx_cli/openapi.json, packaged with the unfoldx dependency;
the tool adapter does not maintain a second response model. Workspace listing supports
limit, cursor, query and state; keep filters unchanged when following next_cursor.
| Tool | Does |
|---|---|
unfoldx_material_upload, unfoldx_material_get |
upload a local file as material; its state |
unfoldx_run_submit, unfoldx_command_get |
send the main agent a message (new or follow-up); find a run by command_id |
unfoldx_run_answer, unfoldx_run_cancel |
answer a card within the budget (else approval_required + approval_url); stop a run |
unfoldx_capabilities, unfoldx_whoami |
what this credential may do, and the skill catalog the web lists |
unfoldx_workspaces_list, unfoldx_workspace_get |
conversations and their runs |
unfoldx_run_status, unfoldx_run_events, unfoldx_run_questions, unfoldx_run_result, unfoldx_run_usage |
one run |
unfoldx_artifact_get, unfoldx_artifact_access |
finished films; access issues a one-hour download link |
JSON Schema validation uses jsonschema; the standard JSON loader reads the sole packaged OpenAPI contract.
The SDK is pinned (mcp==2.3.0) and is a dependency of this package only; the CLI stays
stdlib-only. Tests: cd mcp && uv run pytest tests.
Resource tools (0.6.0)
Resource tool descriptions, scopes, input and output schemas come from unfoldx_cli/openapi.json, bundled once
with the CLI dependency. There is no duplicate YAML or generated return-model registry. tools/list includes
materials, works/exports, catalogs, audition/cover jobs, public shares, publishing accounts/receipts,
brands/assets, preferences/pronunciations, and separate superfast jobs. Each tool states its required scope.
Personal memory, deletes and publishing-platform logins are not exposed; manage them in the UnfoldX web app.
Publishing, sharing and other public actions without their scope answer insufficient_scope with
error.details.approval_url, where the user confirms in the web app.
Writes with side effects do not automatically retry unless their existing service provides idempotency. Destructive
operations require confirm=true. Missing scopes are server-enforced even if a host ignores tool annotations.
unfoldx_work_export writes local files and shares the CLI's atomic no-clobber behavior; overwrite=true is an
explicit replacement. Derived audio requires ffmpeg. Other media tools return signed access links; never log them.
unfoldx_superfast_submit requires a saved command_id and opt-in scope; billing is not_metered, not free. Poll
unfoldx_superfast_status with a bounded interval. No automatic fallback from ordinary runs to superfast.
For a smaller context surface, run unfoldx-mcp --toolsets core,materials,works,catalogs; add domains as needed.
--read-only both removes mutating tools from discovery and rejects direct calls to them. This is a host
configuration boundary in addition to server-side credential scopes, not a substitute for authorization.
Superfast status exposes duration: measured seconds, target seconds and delta. A warning is a quality fact,
not a failed job. Report any deviation clearly; only an explicit caller submission edits the film.
Metadata
Release files for unfoldx-mcp 0.6.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| unfoldx_mcp-0.6.0.tar.gz | 66.8 kB | With provenance | Details for unfoldx_mcp-0.6.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| unfoldx_mcp-0.6.0-py3-none-any.whl | Python 3 | none | any | Details for unfoldx_mcp-0.6.0-py3-none-any.whl |
Total release size: 82.0 kB
Release files / unfoldx_mcp-0.6.0.tar.gz
| Download URL | unfoldx_mcp-0.6.0.tar.gz |
|---|---|
| Size | 66.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
46ffc07d6c54ce685232502d76560e8aa5139623358909d9b0c0778e48926790
|
|
BLAKE2b-256 checksum How to use checksums |
8bc87b10a82476b3aa34c4b725bcdd3a26301f471345ffbcd7afa28f9012b0be
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logRelease files / unfoldx_mcp-0.6.0-py3-none-any.whl
| Download URL | unfoldx_mcp-0.6.0-py3-none-any.whl |
|---|---|
| Size | 15.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ab2767b19bc358c3e7779d2e9991298f205a7cbbd05819cd8b922e5bb1ac3e06
|
|
BLAKE2b-256 checksum How to use checksums |
60696c437bb079df0590e11dbc96e345e83f94abe76d34a3d055398353ed0c99
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logSecurity for unfoldx-mcp 0.6.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for unfoldx_mcp-0.6.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.