Connect an MCP client

Install in Claude

Add JsonCut Studio – Image & Video Editing from the Claude directory, connect your JsonCut account and approve access. No custom-server setup or API key is needed. Follow the Claude installation guide for the complete steps and example prompts.

Endpoint for other MCP clients

For Claude Code and other developer MCP integrations, use this remote Streamable HTTP endpoint:

https://mcp.jsoncut.com/mcp

Connect with OAuth (recommended)

For ChatGPT, Claude Code and other clients supporting remote MCP with OAuth:

1. Add a remote MCP server using the endpoint above. Choose OAuth if the client asks for an authentication method.
2. Follow the sign-in link to JsonCut Studio. Sign in with your usual JsonCut account.
3. Review the app name, return address and requested permissions, then select Allow access.
4. Return to your client. It can now discover JsonCut tools and work with your projects.

You do not need to paste a JsonCut API key. Clients supporting dynamic registration obtain their OAuth client credentials automatically; do not use a JsonCut API key as an OAuth client secret. Connector availability and settings names depend on your client and plan.

For clients configured with JSON and built-in OAuth support:

{
  "mcpServers": {
    "jsoncut": {
      "type": "http",
      "url": "https://mcp.jsoncut.com/mcp"
    }
  }
}

Some clients require a separate authenticate/connect action after adding the server.

Permissions and disconnecting

Each approved connection appears as OAuth · [app name] in Studio’s Developer settings. Delete that entry to revoke access. Your existing plan, usage limits and credits apply. OAuth never grants access to Studio-only account or billing operations.

Access tokens last one hour and compatible clients refresh them automatically. Reconnect after 30 days, after signing out of JsonCut (which revokes the current session), or after revoking a connection. Denying access returns you to the client without granting permissions.

API keys (alternative)

For clients without OAuth or unattended automation, send a 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. For this alternative, choose Remote HTTP or Streamable HTTP, paste the endpoint, then add X-API-Key as a secret header. An API key is not an OAuth bearer token.

Verify the connection

Ask the client to list JsonCut tools, then call jsoncut_get_authoring_guide. A correctly connected V2 MCP server exposes only jsoncut_* 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

OAuth connects the account; it does not give an Agent access to local files or remove its network restrictions. Choose the transfer route that the client actually supports:

Never ask the model to type binary Base64, compress music to fit its context, or bypass a blocked network policy. jsoncut_upload_media remains available for small programmatically encoded files (up to 3 MiB decoded).

For a raw-byte upload:

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. Check jsoncut_get_upload_status with the ticket's session ID. Use its completed media reference in later edits. If the PUT response was lost, check status before retrying.
4. Use jsoncut_abort_upload to discard an unfinished session. A committing or completed upload cannot be cancelled this way.

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

For an Agent with local command execution, configure JSONCUT_API_KEY or JSONCUT_ACCESS_TOKEN securely in its environment, then run:

python mcp/upload_file.py ./soundtrack.wav --project YOUR_PROJECT_ID --mime audio/wav

The helper requires the repository's MCP Python dependencies. It does not send credentials with the ticket PUT or expose them in its output. Media content URLs are authenticated JsonCut API paths, not public download links; resolve relative paths against your API origin and send your normal authorization.

Templates through MCP

An Agent should search templates, call jsoncut_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

The legacy endpoint continues to require X-API-Key; OAuth is available on the V2 endpoint. 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.