MCP for AI agents

Type: How-to · Audience: Claude Desktop users, developers building AI agents

KinoCloud exposes a Model Context Protocol (MCP) server so that AI agents can submit jobs, check status, and manage credits through natural language — no API calls required in the prompt.

---

Available MCP tools

Once connected, the agent has access to 8 tools:

Tool	What it does
estimate_cost	Price a render or simulation job before submitting
submit_render_job	Submit a frame-based render job
submit_simulation_job	Submit a task-based simulation job
get_job_status	Check the lifecycle status of a job
list_jobs	List recent jobs with optional status filter
cancel_job	Cancel a running or queued job
get_job_outputs	Get presigned download URLs for completed outputs
get_credit_balance	Read available credit balance

---

Option A — Claude Desktop (stdio, local)

This runs the MCP server as a local process. The agent communicates via stdin/stdout — no network exposure.

1. Create a KinoCloud API key with scopes jobs:read, jobs:write, credits:read (see Authentication guide).

2. Edit your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "kinocloud": {
      "command": "npx",
      "args": ["-y", "@kinocloud/mcp"],
      "env": {
        "KINOCLOUD_API_KEY": "kc_live_your_key_here",
        "KINOCLOUD_API_URL": "https://app.kinocloud.io"
      }
    }
  }
}

3. Restart Claude Desktop. The KinoCloud tools appear in the tools panel.

---

Option B — Streamable HTTP (remote / hosted)

Use this when your MCP client connects to a URL instead of launching a local process (e.g. Claude.ai remote MCP, custom agent frameworks).

The server runs at https://mcp.kinocloud.io/mcp.

Most MCP clients that support the url form also support a headers block for passing the bearer token:

{
  "mcpServers": {
    "kinocloud": {
      "url": "https://mcp.kinocloud.io/mcp",
      "headers": {
        "Authorization": "Bearer kc_live_your_key_here"
      }
    }
  }
}

If your client does not support per-server headers, use Option A instead.

Security: The remote server performs per-request key validation and forwards your key to /api/v1 on your behalf. It holds no ambient credential — every call is scoped to your key.

---

Example agent workflows

Once connected, you can drive KinoCloud entirely through natural language:

Render a scene:

"Estimate the cost to render frames 1–500 of scene.blend at 1080p EXR, then submit if it's under $5."

Monitor a job:

"What's the status of my last render job? Download the outputs if it finished."

Check balance before submitting:

"How many credits do I have left? Is that enough for a 250-frame render?"

Batch simulation:

"Submit an AutoDock Vina docking screen with 1000 tasks using the ligand dataset I just uploaded."

---

Self-hosting the MCP server

If you need the server on your own infrastructure:

# Install
npm install -g @kinocloud/mcp

# Run Streamable HTTP server (default port 3333)
KINOCLOUD_API_URL=https://app.kinocloud.io kinocloud-mcp-http

Environment variables:

Variable	Default	Description
KINOCLOUD_API_URL	https://app.kinocloud.io	Base URL of the KinoCloud instance
PORT	3333	Port for the Streamable HTTP server
MCP_ALLOWED_HOSTS	(none, allows all)	Comma-separated list of allowed Host header values; set in production

---

Troubleshooting

"Unknown tool" errors: Restart your MCP client after installing the server. The tool list is fetched on connection.

401 Unauthorized from tools: The API key in env (stdio) or headers (HTTP) is invalid or missing the required scope. Verify with curl https://app.kinocloud.io/api/v1/credits/balance -H "Authorization: Bearer YOUR_KEY".

stdio server not starting: Ensure Node.js ≥20 is installed (node --version). The npx -y form downloads the package on first run.