MCP for AI agents

Type: How-to · Audience: MCP users and developers building AI agents

KinoCloud has two distinct MCP surfaces:

• Cloud MCP drives the KinoCloud API: jobs, uploads, inference, billing, and StateBridge controls. Its generated catalogue exposes 24+ tools from packages/mcp/src/tools.ts; query tools/list for the exact catalogue installed on the server.
• Embedded DCC MCP drives the currently running Blender process through a smaller typed scene-command allowlist. Blender is the only publicly listed plugin and remains pending full production qualification. The server is loopback-only, uses a per-session bearer token, and is off until the artist starts it. It does not expose the cloud catalogue.

The cloud package uses the official MCP TypeScript SDK v2 packages. It supports the stateless 2026-07-28 protocol and the stateful dated protocol era through 2025-11-25, including compatible 2025-06-18 clients.

Hosted cloud MCP — API key

A hosted deployment exposes the packaged Streamable HTTP server and authenticates requests with KinoCloud API keys:

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

Use the endpoint supplied by the deployment operator. The repository does not route /mcp through the Netlify web application, so do not assume https://kinocloud.io/mcp is deployed without separate hosting and a verified route. The hosted transport uses API-key bearer authentication, not an OAuth authorization flow.

Local stdio — API key

Use stdio when the client launches a local process:

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

KINOCLOUD_API_KEY is required for stdio. Official MCP conformance in CI targets the running cloud HTTP server because the official server runner is URL-based; it does not establish stdio conformance.

Self-hosted Streamable HTTP — API key

npm install -g @kinocloud/mcp
KINOCLOUD_API_URL=https://kinocloud.io \
MCP_ALLOWED_HOSTS=mcp.example.com \
kinocloud-mcp-http

{
  "mcpServers": {
    "kinocloud-self-hosted": {
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer kc_live_your_key_here"
      }
    }
  }
}

Each POST /mcp must send Authorization: Bearer kc_live_… or kc_test_…. The standalone process binds loopback unless MCP_HOST is explicitly set. Put TLS and any public exposure behind a hardened reverse proxy.

Implemented server environment variables

Variable	Default	Purpose
KINOCLOUD_API_URL	https://kinocloud.io	API origin used by cloud tools
KINOCLOUD_API_KEY	none	Required by stdio; HTTP authenticates each request
PORT	3333	HTTP listen port
MCP_HOST	127.0.0.1	HTTP bind address
MCP_ALLOWED_HOSTS	loopback hosts	Additional comma-separated Host values
MCP_ALLOWED_ORIGINS	loopback origins	Additional comma-separated browser origins
MCP_MAX_BODY_BYTES	1048576	Maximum JSON request body
MCP_RESOURCE_URL	none	Optional protected-resource metadata URL
MCP_AUTHORIZATION_SERVERS	none	Optional authorization-server metadata
MCP_SCOPES_SUPPORTED	none	Optional scopes included in protected-resource metadata
MCP_AUDIT_LOG	true	Set to false to disable structured request audit events

The three metadata variables only publish discovery metadata. They do not provide authorization or token validation and do not change the standalone CLI from API-key authentication. An embedding service must supply its own authenticate integration for another bearer-token scheme.

Embedded DCC MCP

The public Blender plugin includes an embedded server backed by kinocloud.mcp_core.LocalMcpServer. Start it from the KinoCloud panel, copy the generated session token, and connect through the plugin's displayed http://127.0.0.1:<port>/mcp URL or bundled stdio proxy.

The listener is default-off, loopback-only, and token-gated. Commands are schema-validated and marshalled onto the host's main thread where required; arbitrary Python or host-script execution is not exposed. DCC_AGENT_ENABLED gates the hosted Director Chat backend, not whether the local listener starts.

Upload behavior

Cloud upload tools mint intents and presigned URLs; the MCP server never reads a local path or transfers file bytes. The MCP host must read bounded chunks, PUT them directly to object storage, call complete_upload, and pass the returned key to a submit tool. A generic client without filesystem and HTTP transfer capabilities cannot upload files.

Troubleshooting

• Unknown tool: reconnect or restart the client so it refreshes tools/list.
• Hosted/self-hosted 401: verify the API key and required scopes against https://kinocloud.io/api/v1/credits/balance.
• Modern request rejected: send protocol version 2026-07-28 in request metadata and MCP-Protocol-Version, plus matching Mcp-Method and, where required, Mcp-Name headers.
• Stateful request rejected: negotiate a dated protocol revision through 2025-11-25; compatible older clients may negotiate 2025-06-18.
• Embedded DCC connection refused: start MCP inside the host first and use the newly issued session token; tokens do not survive server restarts.