Katechon / Engine MCP contract v1.2.0

Katechon Engine MCP

One remote MCP server over the Katechon ad engine. A brief goes in; a structured spec, still sketches, and a finished cut come out. Ten tools, frozen at v1 — names, arguments, enum values, and error codes do not change inside major version 1; response fields are additive only.

01 Endpoint

https://mcp.katechon.technology/mcp

Transport: Streamable HTTP (MCP). One path serving POST, GET, DELETE.
Session: Stateless — no Mcp-Session-Id. Any two requests may hit different instances.
Response: Adaptive: JSON for simple calls, SSE when the server streams. Send Accept: application/json, text/event-stream.
Version: MCP-Protocol-Version is honored; an unsupported version is answered 400.

02 Auth

Bearer token, provisioned per client. Every request — every method, every path, including /healthz — must carry the header:

Authorization: Bearer YOUR_TOKEN

Anything else is answered 401 with WWW-Authenticate: Bearer and a JSON-RPC -32001 body, before path routing — an unauthorised caller learns nothing about the surface behind it.

Tokens are issued by hand, one per client. Ask for one. OAuth is the target and will supersede the token; the tool contract does not change when it lands.

03 Client config

Standard MCP client config. Replace YOUR_TOKEN with the token you were issued — keep it out of source control.

{
  "mcpServers": {
    "katechon": {
      "type": "http",
      "url": "https://mcp.katechon.technology/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Sanity check from a shell:

curl -sS https://mcp.katechon.technology/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

04 Tools

Tool	Does
workspace_connect	What we know about you; what’s missing.
workspace_onboard	Raw client material → structured workspace. Reserved; not implemented in v1.
ad_intake	Prompt + context → structured questions, including output depth.
ad_plan	Answers → typed spec + deterministic checks + cost/time estimate. Nothing spent.
ad_stills	Stills only → review page → signed URL + images.
ad_render	Continue the same run to a finished cut → review URL + bundle + manifest. `depth`: `kenburns` \| `full`.
run_status	Progress, history, spend for one run.
run_list	History across runs.
report_bug	File a bug or feedback from inside the session — run context attached, tracked on our side.
engine_version	Tag, sha, model versions, contract version.

05 Depths

Three output depths, all live. ad_intake asks which one; the call that produces it differs.

Depth	Call	Time	Cost	Returns
stills	`ad_stills`	1–2 min	~$0.20	Review page of stills. The sane default first call.
kenburns	`ad_render`	3–6 min	$2–5	Cut from the stills, with VO, captions, and music.
full	`ad_render`	20 min – hours	$12–85	Multi-model motion, judged. Async by default — poll `run_status`.

06 Notes

Nothing is spent before ad_plan. The plan returns the estimate; you approve, then render.
Long calls detach. ad_render returns immediately unless you pass wait; poll run_status for phase, progress, and settled spend.
Re-running a completed stage is always legal — skip-if-exists caching makes it near-free, and it is how you recover from a partial failure.
Calling a tool from the wrong phase returns bad_state naming the phase you are in and the tool that advances it.
Errors come in two flavours: protocol errors as JSON-RPC (for the client program), tool errors as isError: true results with a stable code (for the model).
Review pages are handed back as signed URLs on review.katechon.technology — independent auth, safe to send to a human whose browser holds no MCP token.

katechon.technology [email protected] Katechon Technology