Skip to main content

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.

The key never appears in a command or a host config: unfoldx login keeps it in the OS keychain (unfoldx[keychain]) or a 0600 file, and the host config names only the server. An agent can run the setup itself: it runs unfoldx login in the background (the command blocks for up to 10 minutes until the approval), hands the user the link and code as soon as they print, and waits. Skip it when unfoldx whoami already succeeds. A host loads MCP servers when a session starts, so start a new session after adding the server.

uv tool install unfoldx-mcp --with-executables-from unfoldx --with keyring   # or: pip install unfoldx-mcp 'unfoldx[keychain]'
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.7.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for unfoldx-mcp 0.7.0
File Size Uploaded Provenance Actions
unfoldx_mcp-0.7.0.tar.gz 67.1 kB With provenance Details for unfoldx_mcp-0.7.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for unfoldx-mcp 0.7.0
File Interpreter ABI Platform Actions
unfoldx_mcp-0.7.0-py3-none-any.whl Python 3 none any Details for unfoldx_mcp-0.7.0-py3-none-any.whl

Total release size: 82.5 kB

Release files / unfoldx_mcp-0.7.0.tar.gz

Download URL unfoldx_mcp-0.7.0.tar.gz
Size 67.1 kB
Tags Source
SHA-256 checksum
How to use checksums
253393cd0fd5fb1e8cd8b95c5a4282248a84fe1dc1600020b9ede3bb35fa15a6
BLAKE2b-256 checksum
How to use checksums
831b23691f33985c16bcca8bf71af06d7569b430b8b2bcf4c65de6c796116e0d
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 17, 2026.

Transparency log

Release files / unfoldx_mcp-0.7.0-py3-none-any.whl

Download URL unfoldx_mcp-0.7.0-py3-none-any.whl
Size 15.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a1370147890c12c04a92951dd21fb51af4709b2d3c8ef3c467f10f4a964ae748
BLAKE2b-256 checksum
How to use checksums
485045458ea6353747f105567019c7379dd79f2e3bf7f964840bd784aece10c6
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 17, 2026.

Transparency log

Security for unfoldx-mcp 0.7.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.

Select from 2 files

Attestation for unfoldx_mcp-0.7.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 17, 2026.

Transparency log

A 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.

Release history Release notifications | RSS feed

This release

0.7.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page