Skip to main content
View as Markdown

MCP server

decodx exposes an MCP server, so an AI agent can create projects, add scenes, set narration, render and share — using real tools, not a chat box.

What an agent can do​

The server covers the same surface a person has in the web app: create and update projects, add sources, add and reorder scenes, set narration, choose voices and avatars, apply templates and brand settings, estimate and run renders, create shares, and read back jobs, videos and documents.

Connecting a client​

The server lives at https://api.decodx.ai/mcp. You sign in once through your browser (OAuth); the client never sees your password.

  • Claude (web and desktop): Customize → Connectors → Add custom connector, paste the URL, then Connect. On Team and Enterprise, an owner adds it under Organization settings → Connectors.

  • Claude Code: claude mcp add --transport http decodx https://api.decodx.ai/mcp, then run /mcp to sign in. Or install the plugin, which also adds the decodx skill: claude plugin marketplace add decodx-ai/plugins then claude plugin install decodx@decodx.

  • ChatGPT: with developer mode on (Settings → Security and login), add a plugin with the same URL.

  • OpenClaw: in the Control UI, Settings → MCP → Add server, pick Streamable HTTP and paste the URL, then Sign in. In ~/.openclaw/openclaw.json the same entry is:

    { mcp: { servers: { decodx: { url: "https://api.decodx.ai/mcp", transport: "streamable-http", auth: "oauth" } } } }

  • Hermes Agent: add decodx under mcp_servers in your Hermes config; Hermes runs the OAuth sign-in:

    mcp_servers:
      decodx:
        url: "https://api.decodx.ai/mcp"
        auth: oauth

  • Ethos Agent: in the web UI, Plugins → MCP Servers → Add MCP, pick a personality and paste the URL; Ethos handles the sign-in. Or from the CLI: register the server, sign in for a personality, then attach it:

    ethos mcp add --name decodx --url https://api.decodx.ai/mcp
    ethos mcp login decodx --personality <id>
    ethos personality mcp <id> --attach decodx

  • Cursor, VS Code, Gemini CLI and any other MCP client: add the URL as a remote (HTTP) server; the client discovers sign-in from the server's OAuth metadata. A client that can't run OAuth can send a service token as Authorization: Bearer ddx_svc_… instead.

The AI assistants page in the app (second in the sidebar, marked MCP) shows the same steps and lets you review or revoke an agent's access.

How an agent builds a video that renders first time​

  1. Create a project and add scenes. Every change replies with a list of anything still wrong.
  2. preview_scene shows frames of a slide, title, terminal or motion scene, plus any layout problem — text overflowing its box or clipped by the edge — using the same check the render runs.
  3. validate_project runs every pre-render check and returns all issues at once, each with a fix.
  4. estimate_duration shows the length and the AI minutes a render will use.
  5. render_project runs the same checks and only starts a job when they pass; get_job reports progress. Rendering spends AI minutes, so by default a person approves it first: the assistant gets a review link to share, and get_render_request tells it when the render was approved. Admins can let assistants render up to a daily limit, or always, in Settings → Workspace.

The decodx-video skill teaches an agent this loop.

Safe retries and concurrent edits​

Every change accepts an optional idempotency_key: if a call times out, retry it with the same key and it is not applied twice. Pass the project version (from get_project or the last change) as expected_version, and a change made meanwhile by someone else is never overwritten — the call is refused and the agent re-reads the project.

Resources and prompts​

Clients can attach read-only resources without a tool call: the authoring guide with every pre-render check (decodx://guide/authoring), the validation rules, the slide templates, voices, avatars, and any project's scenes (decodx://projects/{project_id}/composition).

Prompts are ready-made recipes in your client's prompt menu: Product demo video, Turn a slide deck into a video, Explainer from notes, and Recording to tutorial.

Authorising an agent​

Agents authorise through OAuth: the agent gets its own grant that you can review and revoke, scoped to your workspace, rather than a shared password.

For unattended automation — a script, a CI job, a backend service — use a service token instead.

Why this is worth using​

An agent driving decodx produces a project you can open, read, edit and re-render. The output isn't a one-shot generation you either accept or throw away — it's an artifact that a person can take over at any point.