content-mcp — Content MCP server

The official MCP server for the Content engine: give Claude, an IDE or any MCP-compatible agent the ability to drive your Content instance — analyze a URL, generate video/audio/subtitles/transcripts, watch the job, land the files in your library. It is an agentic facade over the official Python SDK: no REST of its own, no business logic.

any MCP client → content-mcp (this) → content_sdk → your Content engine (/api/v1)

Install

The server is an ordinary Python application — nothing to clone. There are two shapes, and which one you want depends on who should own the lifecycle.

Let the client fetch it (nothing installed). uvx downloads the server on first use and caches it, so there is nothing to install and nothing left behind. This is the shortest path and the one to prefer:

uvx content-mcp --version       # 0.6.4 — fetched on the spot

Your MCP client then spawns uvx content-mcp instead of a binary (see Connect it to your engine below). pipx run content-mcp does the same if you use pipx.

Or install an executable on your PATH. Pin the version, work offline, or just prefer a command you can run yourself:

uv tool install content-mcp     # isolated, on your PATH
content-mcp --help

# or
pipx install content-mcp

Either way, updating is explicit. This is worth knowing, because it is easy to assume otherwise: uvx reuses the environment it cached and does not re-check PyPI on each run, so a server started this way keeps its version until you say otherwise. Measured, not assumed — a plain uvx content-mcp served 0.6.5 the day 0.6.6 was published.

uvx --refresh content-mcp        # take the newest release
uvx content-mcp@0.6.6            # or pin one, which a client config can do too
uv tool upgrade content-mcp      # for the installed form

Both forms run the same wheel; the difference is only where it lives.

content-mcp on PyPI pulls content-sdk as an ordinary dependency, pinned to the matching release. The wheels are also attached to each GitHub release for air-gapped installs (uv tool install ./content_mcp-<v>-py3-none-any.whl --find-links .).

Connect it to your engine

One environment variable: CONTENT_API_URL (default http://localhost:8010). The server speaks stdio — your MCP client spawns it; you never run it by hand.

Why stdio, and not an HTTP endpoint

A deliberate choice rather than a missing feature, and the reason is the point of the whole project: Content turns resources you already have into artifacts, and a lot of those live on your own machine.

Over stdio the server runs where you do. That is what makes this work:

"Summarize ~/Documents/rapport.pdf"

The file is read on your machine and uploaded to the engine, which may be a NAS in another room. Move the server to an HTTP endpoint next to the engine and that sentence stops meaning anything — the path would resolve on the server's filesystem, so at best it fails, at worst it reads a different file with the same name. No amount of protocol design fixes that: the bytes are where the person is.

Two things follow from it, both worth having:

• No network surface. The engine has no authentication by design (ADR 0024), and an HTTP MCP server would extend that to "anyone who can reach the port can drive it — download, write files, spend your CPU". stdio has no port.
• No service to run. The client starts and stops the process. Nothing to supervise, nothing to restart, nothing left listening after you close the laptop.

What stdio cannot do, plainly: serve a client that cannot spawn a process on your machine — Open WebUI in a container, LibreChat, a hosted web UI. For those, mcpo bridges an stdio MCP server to HTTP/OpenAPI today, and Open WebUI documents it as its own path.

An HTTP transport may still come as a second mode — the SDK does streamable-http with one parameter — for the inverse case: sources that are already remote, and a client that cannot spawn. It would ship bound to loopback by default, and it would have to refuse local paths outright rather than silently resolve them somewhere else. stdio stays the default either way.

Claude Code

# nothing installed — uvx fetches it
claude mcp add content --env CONTENT_API_URL=http://localhost:8010 -- uvx content-mcp

# or, with the executable installed
claude mcp add content --env CONTENT_API_URL=http://localhost:8010 -- content-mcp

Claude Desktop, Cursor, and other clients

Claude Desktop (claude_desktop_config.json), Cursor (.cursor/mcp.json) and any other client using the standard JSON shape:

{
  "mcpServers": {
    "content": {
      "command": "uvx",
      "args": ["content-mcp"],
      "env": { "CONTENT_API_URL": "http://localhost:8010" }
    }
  }
}

With the executable installed instead, drop the args and use "command": "content-mcp".

Then ask for something like "analyze this YouTube URL and download the audio into my library" — the expected flow is get_config → analyze_source → generate → get_job, ending with a delivered_path you can find under the engine's delivery folder.

Logs go to stderr (stdout carries only the MCP JSON-RPC framing), so a client's log pane shows them without corrupting the session.

What it supports today

Everything below has been driven over stdio against a running engine, not inferred from the code.

What needs a runner. The engine reports a capability as unavailable rather than failing halfway, so ask analyze_source first and believe it. Summaries, translations and derived chapters need a local Ollama or a configured cloud key; transcripts need existing subtitles, or the optional Whisper runner for audio without them.

What it does not support

Stated plainly, because finding out by trying is a bad first impression.

What is coming

Written down so the gaps read as a plan rather than as neglect. None of it is implemented; each links to where the decision lives.

• Retrying only what failed — a twenty-video playlist with one failure should cost one member, not twenty (ADR 0025, proposed).
• Playlist synchronization — keeping a local folder in step with a playlist as it changes (M2, the half not yet built).
• Retention — reclaiming disk without touching the user's library (ADR 0023, proposed).
• More document readers, and OCR — the formats listed as refused above.
• An HTTP transport as a second mode — for clients that cannot spawn a process (Open WebUI, hosted UIs). Not a replacement: see Why stdio above for what it would cost, and mcpo for what works today.

Something you need that is not here? The gap list is the roadmap's front door: open an issue.

Tools (intention-level, not one-per-endpoint)

Resources (read-only, content:// namespace)

content://analyses/{id}, content://jobs/{id}, content://artifacts/{id} — JSON views for a host to attach as context. Prompts are intentionally not provided yet.

Where downloaded files land

download_artifact writes to the machine running this server — the counterpart to delivery, which writes to the engine's library. One variable bounds it:

The refusal is deliberate. An MCP server writes to a real filesystem on an agent's say-so, so widening that is the operator's decision, taken once, rather than something a prompt can talk it into.

When something goes wrong

Every tool translates the SDK's exceptions into something an agent can act on, because the alternative is what this server used to say when the engine was not running: [Errno 61] Connection refused. It names neither what failed nor what to do, and it is the first thing a new user meets — the engine listens on 8010 on the host and 8000 only inside its container, so pointing at the wrong one is the ordinary mistake.

Design

• service.py — the intention logic; takes an SDK client, returns JSON. No MCP imports, no HTTP. Fully unit-tested over a mock transport.
• server.py — thin wiring: registers the tools/resources on an MCPServer and runs stdio. content-mcp → content_mcp.server:main.
• The layering is enforced by tests: the MCP server may import content_sdk only — never an HTTP client, never backend internals (tests/test_layering.py at the repo root).

Where an uploaded file goes, and for how long

A local path handed to analyze_source leaves this machine. The answer says so, rather than leaving it to documentation nobody opens at that moment:

"upload": {
  "upload_id": "upl_…",
  "filename": "report.pdf",
  "size_bytes": 1583,
  "stored_on": "http://nas.local:8010",
  "retention": "deleted 24h after last use",
  "remove_with": "delete_upload"
}

stored_on names the engine rather than a path, because the store is engine-owned and no path here would address it. retention is read from the engine, not assumed: the TTL is the operator's setting, and an engine too old to report it answers unknown rather than a comfortable guess — claiming "no expiry" when the default is 24h would be a falsehood in the reassuring direction. get_config carries the same policy up front, before anything is sent.

The TTL runs from an upload's last use, not its creation, so retrying a job still finds its input.

Local files, both directions

A path you give analyze_source is a path on the machine running this server, never on the engine: the file is read here and uploaded, which is the only way a local file becomes usable by an engine running elsewhere. Identical path strings on two machines do not imply identical filesystems, so the path is never passed through untouched.

download_artifact is the mirror image — it brings a finished artifact back to this machine, bounded by CONTENT_MCP_DOWNLOAD_DIR (see above).

For development

From a clone:

make install    # editable installs of the engine, SDK, CLI and MCP in one venv
claude mcp add content --env CONTENT_API_URL=http://localhost:8010 \
  -- apps/backend/.venv/bin/python -m content_mcp.server

Build the distributions with make wheels (they land in dist/).

Verification status

• Service logic over a mock transport: verified (tests/test_service.py).

• The MCP wiring against the real mcp library (tools, resource templates): verified (tests/test_server.py).

• The full journey — MCP service → SDK → real FastAPI engine → executor → delivery library, including delivery intent and mode: "none": verified in-process (tests/test_end_to_end.py, in make validate).

• The published wheel (uv tool install content-mcp, 0.6.0 from PyPI) driven over stdio by an MCP client session against a running 0.6.0 engine: verified 2026-08-21. What was actually run, end to end:

  Path	Result
  stdio handshake, tools/list, resources/templates/list	9 tools, the three content:// templates
  get_config → analyze_source → list_capabilities → generate → get_job → get_artifact	a web page produced a delivered markdown artifact, inlined as text
  A real YouTube download	audio (opus), 7.5 MB, delivered under its display name
  A binary artifact through get_artifact	not inlined — reference only, as designed
  download_artifact into CONTENT_MCP_DOWNLOAD_DIR	file written on this side
  download_artifact to a path outside it	refused, with the variable named
  A playlist with scope: "each_item"	19 entries → 19 artifacts, numbered 001 - …, one delivered file each
  Engine unreachable / wrong port	actionable message (see below) — this is what the run fixed

  Re-run it after any transport change; the in-process suites above never reach a closed socket, which is exactly how the error-message defect survived.