MCP Reference

The Model Context Protocol (MCP) is the foundation of SwiftyClip's agentic capabilities.

What's MCP?

The Model Context Protocol is an open standard that enables AI models to securely interact with local data and tools. By providing a standardized interface between Large Language Models (LLMs) and applications, MCP allows agents to perform complex tasks like filesystem operations, data analysis, and professional video editing without manual intervention.

SwiftyClip implements the MCP specification to expose its core clipping and rendering engines to agents. This allows tools like Claude Desktop or ChatGPT Codex to drive your entire video production pipeline directly. For more details, visitmodelcontextprotocol.io.

Quickstart

The SwiftyClip binary includes a built-in MCP server that communicates over standard input/output. To start the server, use the following command:

swiftyclip mcp

To integrate with Claude Desktop, add the swiftyclip command to yourconfig.jsonunder the mcpServers key. For Codex users, reference the binary in your local config pattern to enable the clip toolset.

Security model

SwiftyClip's MCP implementation is designed with a "security-first" philosophy. The server operates on a per-token allowlist, ensuring that only authorized agents can issue commands to the clipping engine.

All communication is handled via a loopback-only TCP bridge or local stdio, preventing external network access to the server. The MCP server itself makes no outbound network calls; all social scheduling and rendering logic is executed locally on your Mac.

Troubleshooting

SwiftyClip not running: Most tools require the main SwiftyClip.app to be active. If you receive this error, simply launch the application and retry the command.
Port conflicts: The local bridge uses a specific range of loopback ports. Ensure no other firewall or security software is blocking internal communication on localhost.
Rotating tokens: If an agent can no longer connect, you may need to refresh your MCP token in the SwiftyClip Settings > Developer pane and update your configuration.

Tool Reference

A comprehensive list of all tools exposed by the SwiftyClip MCP server.

clip.ingest

Imports a local video file into the SwiftyClip library for processing. It creates a new project and returns the unique project ID and resolved source path.

Request Example

{
  "method": "tools/call",
  "params": {
    "name": "clip.ingest",
    "arguments": {
      "path": "/Users/okabe/Videos/vlog-01.mp4"
    }
  }
}

Response Example

{
  "content": [
    {
      "type": "text",
      "text": "{\"projectId\": \"550e8400-e29b-41d4-a716-446655440000\", \"sourcePath\": \"/Users/okabe/Videos/vlog-01.mp4\"}"
    }
  ],
  "isError": false
}

Common Errors

•Missing required param 'path'
•File not found at provided path
•SwiftyClip not running

clip.listProjects

Retrieves a list of all active projects in the SwiftyClip library. Each entry includes metadata like the project ID, title, and current analysis status.

Request Example

{
  "method": "tools/call",
  "params": {
    "name": "clip.listProjects",
    "arguments": {}
  }
}

Response Example

{
  "content": [
    {
      "type": "text",
      "text": "{\"projects\": [{\"id\": \"550e...\", \"title\": \"vlog-01\", \"status\": \"ready\"}]}"
    }
  ],
  "isError": false
}

Common Errors

•SwiftyClip not running

clip.listSegments

Lists all candidate clips (segments) identified for a specific project. This includes timing information, virality scores, and generated hook text for each segment.

Request Example

{
  "method": "tools/call",
  "params": {
    "name": "clip.listSegments",
    "arguments": {
      "projectId": "550e8400-e29b-41d4-a716-446655440000"
    }
  }
}

Response Example

{
  "content": [
    {
      "type": "text",
      "text": "{\"segments\": [{\"id\": \"a1b2...\", \"startSeconds\": 12.5, \"endSeconds\": 45.0, \"viralityScore\": 0.85, \"hookText\": \"How to grow your vlog\"}]}"
    }
  ],
  "isError": false
}

Common Errors

•Missing required param 'projectId'
•Invalid UUID for 'projectId'
•SwiftyClip not running

clip.render

Initiates the rendering process for a specific segment. The resulting video will include burn-in captions and apply the requested framing and aspect ratio.

Request Example

{
  "method": "tools/call",
  "params": {
    "name": "clip.render",
    "arguments": {
      "segmentId": "a1b2c3d4-e5f6-4g7h-8i9j-k0l1m2n3o4p5",
      "aspect": "portrait9x16",
      "framing": "faceTracked"
    }
  }
}

Response Example

{
  "content": [
    {
      "type": "text",
      "text": "{\"exportedURL\": \"file:///Users/okabe/Movies/SwiftyClip/vlog-01_clip_1.mp4\"}"
    }
  ],
  "isError": false
}

Common Errors

•Missing required param 'segmentId'
•Invalid UUID for 'segmentId'
•SwiftyClip not running

clip.exportToDesktop

Copies a rendered clip to the user's Desktop folder for easy access. Optionally opens a Finder window to reveal the newly created file.

Request Example

{
  "method": "tools/call",
  "params": {
    "name": "clip.exportToDesktop",
    "arguments": {
      "segmentId": "a1b2c3d4-e5f6-4g7h-8i9j-k0l1m2n3o4p5",
      "openInFinder": true
    }
  }
}

Response Example

{
  "content": [
    {
      "type": "text",
      "text": "{\"path\": \"/Users/okabe/Desktop/vlog-01_clip_1.mp4\"}"
    }
  ],
  "isError": false
}

Common Errors

•Missing required param 'segmentId'
•Segment has not been rendered yet
•SwiftyClip not running

clip.transcribe

Triggers a high-accuracy, on-device transcription of the project's audio. This generates word-level timestamps used for caption rendering and analysis.

Request Example

{
  "method": "tools/call",
  "params": {
    "name": "clip.transcribe",
    "arguments": {
      "projectId": "550e8400-e29b-41d4-a716-446655440000"
    }
  }
}

Response Example

{
  "content": [
    {
      "type": "text",
      "text": "{}"
    }
  ],
  "isError": false
}

Common Errors

•Missing required param 'projectId'
•Invalid UUID for 'projectId'
•SwiftyClip not running

clip.analyze

Runs advanced vision and audio analysis on the project. This detects faces, identifies scene cuts, and analyzes audio energy to find the most engaging moments.

Request Example

{
  "method": "tools/call",
  "params": {
    "name": "clip.analyze",
    "arguments": {
      "projectId": "550e8400-e29b-41d4-a716-446655440000"
    }
  }
}

Response Example

{
  "content": [
    {
      "type": "text",
      "text": "{}"
    }
  ],
  "isError": false
}

Common Errors

•Missing required param 'projectId'
•Invalid UUID for 'projectId'
•SwiftyClip not running

clip.scoreSegments

Evaluates and scores all potential segments for virality and engagement. It automatically de-duplicates overlapping segments and returns the top results.

Request Example

{
  "method": "tools/call",
  "params": {
    "name": "clip.scoreSegments",
    "arguments": {
      "projectId": "550e8400-e29b-41d4-a716-446655440000",
      "targetCount": 5
    }
  }
}

Response Example

{
  "content": [
    {
      "type": "text",
      "text": "{\"segments\": [{\"id\": \"a1b2...\", \"viralityScore\": 0.92}, {\"id\": \"c3d4...\", \"viralityScore\": 0.88}]}"
    }
  ],
  "isError": false
}

Common Errors

•Missing required param 'projectId'
•Transcription and analysis must be completed first
•SwiftyClip not running

clip.schedule

Places a rendered clip into the social media scheduling queue. You can specify the target platform, posting time, and provide an optional caption.

Request Example

{
  "method": "tools/call",
  "params": {
    "name": "clip.schedule",
    "arguments": {
      "segmentId": "a1b2c3d4-e5f6-4g7h-8i9j-k0l1m2n3o4p5",
      "platform": "tiktok",
      "scheduledAt": "2026-05-01T10:00:00Z",
      "caption": "Check out my latest vlog!"
    }
  }
}

Response Example

{
  "content": [
    {
      "type": "text",
      "text": "{\"scheduleId\": \"s1t2u3v4-w5x6-y7z8-a9b0-c1d2e3f4g5h6\"}"
    }
  ],
  "isError": false
}

Common Errors

•Missing required param 'segmentId', 'platform', or 'scheduledAt'
•Social platform account not connected
•SwiftyClip not running