Connect an MCP client

Endpoint

Use the remote Streamable HTTP endpoint for every new integration:

https://mcp.jsoncut.com/mcp

Send your JsonCut API key as the X-API-Key header. Grant only the scopes needed for projects, templates, media, renders and resource discovery.

Generic remote MCP configuration:

{
  "mcpServers": {
    "jsoncut": {
      "type": "http",
      "url": "https://mcp.jsoncut.com/mcp",
      "headers": {
        "X-API-Key": "${JSONCUT_API_KEY}"
      }
    }
  }
}

Client configuration keys differ slightly. In clients with a visual connector dialog, choose Remote HTTP or Streamable HTTP, paste the endpoint, then add X-API-Key as a secret header.

Verify the connection

Ask the client to list JsonCut tools, then call jsoncut_v2_get_authoring_guide. A correctly connected V2 MCP server exposes only jsoncut_v2_* tools. If you see JSON job tools, the client is using the V1 endpoint.

Recommended Agent behavior

1. Read the authoring guide once at the start of a creation task.
2. Use a durable project for iterative image or video work.
3. Upload or discover owned media before referencing it.
4. Make bounded edits, preserving the current optimistic version.
5. Validate and request visual review frames or a contact sheet.
6. Repair only visible problems, then render the pinned final version.

For a simple short video, keep the project flat. For a long video, create meaningful editorial scenes and work scene by scene. The Agent does not need to resend the complete source on every turn.

Uploading local files

Small files can use the bounded Base64 tool. Large or private local files use jsoncut_v2_create_upload_ticket:

1. Request a ticket scoped to exactly one project or template.
2. Upload the declared raw bytes once to the returned uploadUrl with Content-Type: application/octet-stream.
3. Use the returned normal media record in later edits.

Tickets expire after 60 to 900 seconds, reveal no object-storage credentials, and cannot be reused after success, expiry or a size mismatch.

Templates through MCP

An Agent should search templates, call jsoncut_v2_get_template_inputs, upload any needed media, then render values that satisfy the discovered contract. It should not infer fields from a thumbnail or title.

V1 MCP compatibility

Existing legacy clients may continue at:

https://mcp.jsoncut.com/legacy/mcp

Do not configure both endpoints in one Agent. The legacy endpoint is frozen for JSON-job compatibility and does not receive new authoring features.

See every V2 MCP tool and the recommended loops.