@mixio-pro/mcp

small local helper that lets AI assistants (Claude Desktop, Cursor, Claude Code,...) work with files on your computer and Mixio Studio at same time.

It does two things:

1. Caches your files. When you ask assistant to use local file (video, image, audio clip, script, etc.), this helper streams it to Mixio Inference Files once, associates the durable URL with Mixio Studio, and remembers the result. Next time you reference the same file, no re-upload. If the file changes or its public URL is empty, it auto-uploads again.
2. Connects to your Studio account. assistant gets the Studio MCP tools currently exposed by your hosted Mixio account through one local entry point.

Quick install

You need:

• Node.js 22 or newer (npm 12 requires Node.js 22.14 or newer).
• Mixio Studio API key. Get it from your Studio settings → API keys.
• npm 12 users must explicitly allow the package's native SQLite dependency. The MCP configuration below grants only the better-sqlite3 install script permission.

Add this to your AI assistant's MCP config (one of ~/.claude/claude_desktop_config.json, ~/.cursor/mcp.json, project-level .mcp.json, etc.):

{
  "mcpServers": {
    "mixio": {
      "command": "npx",
      "args": ["--yes", "--allow-scripts=better-sqlite3", "@mixio-pro/[email protected]"]
    }
  }
}

Supply MIXIO_API_KEY through your host's secret store or the environment inherited by the MCP launcher. Keep literal keys out of shared JSON and source control; on POSIX systems, restrict credential-bearing configuration to mode 0600.

If your assistant does not pass the --allow-scripts flag through to npx, approve the same dependency once for your user account instead:

npm config set allow-scripts=better-sqlite3 --location=user

Restart the assistant. No project build step is required; do not use --dangerously-allow-all-scripts.

Optional automatic updates

The stdio server keeps the current release by default. To check for a newer release at startup without changing anything, set MIXIO_MCP_AUTO_UPDATE=notify. To have it relaunch itself through npx when a newer release is available, set MIXIO_MCP_AUTO_UPDATE=apply:

{
  "env": {
    "MIXIO_MCP_AUTO_UPDATE": "apply"
  }
}

Updates are opt-in because applying one starts a new package process and requires network access to the npm registry. The replacement inherits the MCP stdio streams and API-key environment, and a failed check or update falls back to the current release. MIXIO_MCP_AUTO_UPDATE_TIMEOUT_MS controls the registry check timeout (default 2000 ms). The one-shot MIXIO_MCP_AUTO_UPDATE_ATTEMPT marker prevents an updated process from recursively updating itself.

What you get

Once it's running, your assistant has these tools:

| Tool | What it does | | ----------------------------- | ------------------------------------------------------------------------------------------------ | | upload_file | Upload a local file through Inference Files and associate it with Studio. Hash-aware, so calling it twice on the same file uses the cache. | | get_public_url | Get the Mixio URL for any local file. Auto-uploads on first call. | | list_cached_files | See everything cached so far. | | forget_path / clear_cache | Drop a single entry or wipe the cache. | | studio_get_contract | Read a versioned hosted contract for a tool, generation use case, element type, or project settings. | | studio_* | Hosted Studio MCP tools discovered at startup and mounted locally with the studio_ prefix. |

upload_file and get_public_url accept only these optional Media categories: source, generated_frame, generated_video, reference, voiceover, music, sfx, and final. screenplay is a Studio element type, not a Media category; use source for an uploaded screenplay file or leave the category unset.

Hosted discovery and contract reads

The local server proxies the hosted Slice 1 discovery/read tools and direct contract lookup; it does not implement a second copy. These hosted tools are available through the following local aliases:

| Hosted tool | Local alias | Purpose | | ------------------------------- | -------------------------------------- | ----------------------------------------- | | search_tools | studio_search_tools | Find compact catalog entries. | | describe_tools | studio_describe_tools | Load exact candidate definitions. | | get_element_detail | studio_get_element_detail | Read one bounded canonical element. | | get_action_detail | studio_get_action_detail | Read one action and its optional receipt. | | get_generation_catalog_detail | studio_get_generation_catalog_detail | Read one generation configuration. | | get_job_detail | studio_get_job_detail | Read one bounded production job. | | get_contract | studio_get_contract | Read a versioned tool, generation, element, or project-settings contract. |

The hosted endpoint is stateless Streamable HTTP. This package authenticates with MIXIO_API_KEY, discovers hosted tools at startup, and prefixes their names with studio_. Catalog responses include a stable digest so callers can notice changes. The six canonical reads are scoped and bounded: 32,768-byte input, 262,144-byte output, and 10-second limits; search returns at most 50 entries, describe at most 10, and each resource read returns one record. search_tools includes compact metadata for the 56 direct hosted tools as well as the six canonical definitions, while describe_tools can load complete input/output schemas only for the six canonical definitions. studio_get_contract exposes versioned, digested schemas, examples, constraints, and applicable semantic rules for any hosted direct tool as well as generation, element, and project-settings targets; it is the preferred direct-tool schema read instead of relying only on MCP tools/list.

Hosted 1.1.0 projects all 62 tools from the canonical get_contract registry. The public route preserves text results and adds schema-validated structuredContent; raw ping becomes { "message": "pong" } there. Invalid known outputs retain their text and return an MCP error. The bridge preserves these results and hosted outputSchema, all four safety annotations, and _meta under the prefixed names. src/server.ts snapshots every authenticated discovery page at startup and overlays metadata after FastMCP prefixing; restart the bridge to refresh that snapshot. If the proxy connection fails, the five local tools remain available. If only the metadata snapshot fails after a proxy connection, hosted studio_* tools remain available without the optional enriched metadata. With the full hosted catalog, clients see 67 tools across all pages. Startup diagnostics are stage-specific and safe to share: MIXIO_MCP_UPSTREAM_PROXY_CONNECT_FAILED means only local tools are available, while MIXIO_MCP_UPSTREAM_METADATA_UNAVAILABLE means the hosted proxy remains usable without optional enrichment. Neither diagnostic includes the configured URL, error text, or credential.

The five local schemas declare JSON Schema draft 2020-12. Upload-capable tools advertise non-read-only, non-idempotent, open-world behavior even when a particular call hits the cache. Cache deletion is destructive only to local mappings.

Evaluation uses studio_evals_list_evaluation_catalog, studio_evals_evaluate_media, and studio_evals_get_evaluation_result locally; direct hosted clients use the same names without studio_. Resolve the Studio project with studio_list_projects, read the current tool contracts, submit once, and poll with the returned runId. Submission and result success envelopes are { ok, runId, status, terminal, threshold, evaluation }; native receipt fields remain under evaluation. studio_run_eval, studio_run_evaluation, and studio_get_evaluation_result remain deprecated hosted aliases through 1.1.x, with removal in hosted 2.0.0. Evaluation and asset registration are not local tools.

Generation submission, mutations, and job observe/cancel/recover/result tools are not part of the six-tool canonical Slice 1 discovery-read catalog, but remain available on the broader hosted direct tool surface. Hosted OAuth and endpoint hardening are shipped independently: remote MCP hosts use OAuth, while this local package remains the API-key stdio fallback for Claude Code and other local-only clients. Present browser origins are checked against the exact configured trusted-origin set before authentication, while clients without Origin remain compatible. API keys support the additive profiles mcp.read, mcp.production-write, mcp.generation, and mcp.destructive; new keys default to read-only. In observe mode the hosted route records would-deny decisions without changing current valid-key behavior. In enforce mode it filters tools/list and rejects unauthorized tools/call before execution; off is the authorization rollback mode. Rate/usage limits, OAuth capability filtering, and action-ledger mutation migration remain follow-up work. See resources/mcp.md for remote OAuth provider setup and the current shipped/deferred boundary.

List/query tool response shape

Beyond the bounded Slice 1 reads above, the hosted server also proxies a wider production CRUD surface (studio_list_projects, studio_list_episodes, studio_query_elements, studio_query_relations, studio_create_element, etc.) under the studio_ prefix. Its list_*/query_* tools return a compact per-row shape by default — id, name/title, type, and a small set of summary fields — instead of the full Payload record, since e.g. an episode's metadata.fullScript alone can run 8-23KB+ per row. Pass includeFull: true or an explicit fields: string[] allowlist to opt into full records. Single- record get_* tools (get_project, get_episode, get_element) are unaffected and still return full detail by default.

How file caching works

• Each file is hashed (SHA-256) on first use.
• mapping local path ↔ hash ↔ Mixio URL is stored in small SQLite database at ~/.mixio/mcp-cache.db.
• Two different paths to same content reuse one upload (deduped by hash).
• Edit file in place? cache notices on next call and re-uploads.
• Multiple sessions can share cache safely (WAL mode, multi-process safe).

Configuration

All optional. Defaults work for most people.

| Variable | Default | What it does | | ------------------------------------------- | ---------------------------- | ------------------------------------------------ | | MIXIO_API_KEY | — (required) | Your Studio API key. | | MIXIO_BASE_URL | https://studio.mixio.pro | Studio URL. Override for staging or self-hosted. | | MIXIO_INFERENCE_FILES_URL | https://inference.mixio.pro/files | Inference Files upload endpoint. | | MIXIO_HOME | ~/.mixio | Where the cache lives. | | MIXIO_FASTMCP_CACHE | ${MIXIO_HOME}/mcp-cache.db | Override cache path. | | MIXIO_FASTMCP_TIMEOUT_MS | 60000 | HTTP timeout for non-upload calls. | | MIXIO_FASTMCP_UPLOAD_TIMEOUT_MS | 600000 | Upload timeout; long calls also emit MCP progress. | | MIXIO_FASTMCP_UPSTREAM_CONNECT_TIMEOUT_MS | 10000 | How long to wait for Studio MCP at startup. | | MIXIO_MCP_AUTO_UPDATE | off | off, notify, or apply a newer npm release at startup. | | MIXIO_MCP_AUTO_UPDATE_TIMEOUT_MS | 2000 | Registry check timeout for auto-update. | | MIXIO_MCP_AUTO_UPDATE_REGISTRY_URL | npm registry | Latest-version endpoint used for the update check. |

Large stdio uploads are synchronous because the MCP client reserves a presigned Inference Files upload, sends the bytes directly to object storage, waits for Inference to confirm the durable object, and then creates the scoped Studio Media record. Files at or below 5 MB use the authenticated Inference proxy; larger files use the presigned flow. Inference receives only the user-facing API key through x-api-key, and that key is not sent to object storage; the server-only INFERENCE_INTERNAL_SERVICE_TOKEN is never sent to the local client. The client probes the public URL before caching it, so an active zero-byte object cannot be returned as a successful upload. Browser uploads continue to use the Studio /api/media multipart path.

Running from source (developers)

git clone <this-repo>
cd packages/mcp
pnpm install
pnpm build
node dist/bin.js # inherits MIXIO_API_KEY from the launcher environment

Tests: pnpm test. The suite covers cross-OS path handling, multi-process cache concurrency, drift detection, long-upload progress, npm 12 installation guidance, input schemas, and end-to-end stdio.

Publishing (maintainers)

The repository publishes this package from mcp-v<version> tags through GitHub Actions and npm trusted publishing. Configure the relationship once from a maintainer terminal (the package must already exist and account-level 2FA must be enabled):

npx --yes [email protected] login --auth-type=web
npx --yes [email protected] trust github @mixio-pro/mcp \
  --repository mixiopro/studio \
  --file publish-mcp.yml \
  --allow-publish

After updating the version in package.json, create and push the matching tag:

git tag mcp-v0.6.2
git push origin mcp-v0.6.2

The workflow runs the package tests, a named upstream-failure-boundary guard, typecheck, npm 12 packed-install smoke test, and high-severity production audit before publishing. It uses a short-lived OIDC credential, so no NPM_TOKEN or NODE_AUTH_TOKEN is stored in GitHub Actions.

License

MIT. See LICENSE.