> ## Documentation Index
> Fetch the complete documentation index at: https://developers.fastdrop.io/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Setup

> Connect AI agents to FastDrop via the Model Context Protocol

FastDrop exposes an [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that lets AI agents classify, transcribe, and search videos through natural language.

## What is MCP?

MCP is an open standard that lets AI applications discover and use external tools. When you connect FastDrop's MCP server to an AI agent, the agent can:

* Classify videos by URL
* Transcribe and translate video audio
* Search across transcribed videos by keyword or meaning
* Check job status and results
* Submit batch jobs
* Check your credit balance

All through natural conversation — no code required on your end. Works with any video content: interviews, lectures, recordings, raw footage.

## Setup

Add FastDrop to your AI client's MCP configuration. Your API key goes in the `X-API-Key` header, so the agent authenticates automatically and you never paste your key into a conversation.

<Tabs>
  <Tab title="Claude Desktop">
    Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

    ```json theme={null}
    {
      "mcpServers": {
        "fastdrop": {
          "url": "https://api.fastdrop.io/mcp",
          "headers": {
            "X-API-Key": "fd_live_your_key_here"
          }
        }
      }
    }
    ```

    Restart Claude Desktop after saving.
  </Tab>

  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add --transport http fastdrop https://api.fastdrop.io/mcp \
      --header "X-API-Key: fd_live_your_key_here"
    ```
  </Tab>

  <Tab title="Cursor">
    Go to **Settings > MCP Servers** and add:

    ```json theme={null}
    {
      "mcpServers": {
        "fastdrop": {
          "url": "https://api.fastdrop.io/mcp",
          "headers": {
            "X-API-Key": "fd_live_your_key_here"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="VS Code (Copilot)">
    Add to your VS Code `settings.json`:

    ```json theme={null}
    {
      "mcp.servers": {
        "fastdrop": {
          "url": "https://api.fastdrop.io/mcp",
          "headers": {
            "X-API-Key": "fd_live_your_key_here"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Windsurf">
    Add to your MCP configuration:

    ```json theme={null}
    {
      "mcpServers": {
        "fastdrop": {
          "url": "https://api.fastdrop.io/mcp",
          "headers": {
            "X-API-Key": "fd_live_your_key_here"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

Don't have a key yet? [Create one here](https://fastdrop.io/developers) — the free tier includes 100 credits and needs no card.

### Installing from an MCP directory

FastDrop is listed on [Smithery](https://smithery.ai/server/horizonindustry/fastdrop) as `horizonindustry/fastdrop`. Installing from there routes your calls through Smithery's gateway rather than connecting to `api.fastdrop.io` directly; everything else — the tools, the credit costs, the behaviour — is identical.

The listing asks for a **FastDrop API Key**, and it is optional. Leave it blank and you can still browse the tools and call `fastdrop.capabilities.list`, which needs no key. Every tool that does real work — classification, transcription, batches, search — needs one, so fill it in when you have it. A key entered there reaches us as an `X-API-Key` header, not as part of the URL.

## Authentication

Send your `fd_live_...` key as an **`X-API-Key` HTTP header** in your client config, as shown above. If your client only supports bearer tokens, `Authorization: Bearer fd_live_...` works too.

<Warning>
  Don't paste your API key into the chat. A key sent as a header stays between your client and FastDrop. A key typed into a conversation becomes part of the transcript your AI provider stores and processes.
</Warning>

Every tool also accepts an `api_key` parameter. This is **deprecated** and exists only so older configurations keep working — it puts your key in the model's context. If you set one up that way, move it to the header.

The server also accepts `?apiKey=fd_live_...` on the endpoint URL. That exists for MCP directories and gateways that can only pass configuration as a query string; a header always takes precedence over it. Prefer the header when your client supports one, since URLs are logged in more places than headers are.

`fastdrop.capabilities.list` needs no key at all.

## Available tools

Once connected, your AI agent can use these 12 tools. Names form a tree — `fastdrop.<domain>.<verb>` — over five domains, so the surface stays browsable and can't collide with other MCP servers you have installed.

| Tool | Description | Credits |
| - | - | :-: |
| `fastdrop.video.classify` | Submit a video URL for classification | 1-6 |
| `fastdrop.video.readiness` | Decide whether footage suits an intended use, before processing it | 1 |
| `fastdrop.video.fix` | Execute the fix readiness prescribed, then re-check the result | by duration |
| `fastdrop.video.thumbnails` | Extract keyframe thumbnails from a video | 1 |
| `fastdrop.video.diagnostics` | Analyze video codec, resolution, FPS, VFR, health | 1 |
| `fastdrop.video.fingerprint` | Generate perceptual hash for duplicate detection | 1 |
| `fastdrop.video.clips` | Find clip candidate timestamps | 2 |
| `fastdrop.video.transcribe` | Transcribe, translate, and generate SRT/TXT subtitles | 5 |
| `fastdrop.batch.classify` | Submit up to 50 videos at once | varies |
| `fastdrop.batch.status` | Poll batch progress | 0 |
| `fastdrop.batch.search` | Search transcribed videos by keyword or meaning | 0 |
| `fastdrop.job.status` | Poll a job by ID for results | 0 |
| `fastdrop.account.usage` | View credit balance and usage stats | 0 |
| `fastdrop.capabilities.list` | List capabilities and credit costs (no key needed) | 0 |

Every `fastdrop.video.*` tool except `classify` and `readiness` is shorthand for `fastdrop.video.classify` with a single capability. `readiness` is not — it returns a verdict in the same call rather than a job to poll. If you want more than one thing from a video, ask for them together — one call with several capabilities is cheaper and faster than several calls.

<Warning>
  **Tool names changed on 11 August 2026.** The previous `fastdrop_*` snake\_case
  names have been replaced by the dot-notation names above, with no aliases. If
  you have an agent prompt, script, or workflow that names a tool explicitly,
  update it using the mapping below. Nothing else changed — same endpoint, same
  authentication, same parameters, same behaviour.

  | Old name | New name |
  | - | - |
  | `fastdrop_classify_video` | `fastdrop.video.classify` |
  | `fastdrop_extract_thumbnails` | `fastdrop.video.thumbnails` |
  | `fastdrop_run_diagnostics` | `fastdrop.video.diagnostics` |
  | `fastdrop_generate_fingerprint` | `fastdrop.video.fingerprint` |
  | `fastdrop_detect_clips` | `fastdrop.video.clips` |
  | `fastdrop_transcribe_video` | `fastdrop.video.transcribe` |
  | `fastdrop_classify_batch` | `fastdrop.batch.classify` |
  | `fastdrop_get_batch_status` | `fastdrop.batch.status` |
  | `fastdrop_search_batch_transcripts` | `fastdrop.batch.search` |
  | `fastdrop_get_job_status` | `fastdrop.job.status` |
  | `fastdrop_check_usage` | `fastdrop.account.usage` |
  | `fastdrop_list_capabilities` | `fastdrop.capabilities.list` |

  Most setups need no change at all: agents discover tools by listing them, so
  anything that just says "classify these videos" keeps working after a client
  restart.
</Warning>

<Note>
  **Transcription costs less in a batch.** Asking for `transcribe` inside
  `fastdrop.batch.classify` costs **3 credits** per video rather than 5. Batches
  return the transcript and translation but cannot generate SRT/TXT subtitle
  files, so you are not charged for a step that can't run. Use
  `fastdrop.video.transcribe` when you need the subtitle files.
</Note>

<Note>
  **Searching a batch requires transcription.** Include `transcribe` in the
  capabilities you pass to `fastdrop.batch.classify`, and wait for the batch to
  reach `completed` — search is unavailable while videos are still processing.
  Three modes are supported: `keyword` (full-text), `semantic` (meaning-based),
  and `hybrid` (both, the default).

  Visual search is a subscriber feature on fastdrop.io and is not exposed over MCP.
</Note>

Read-only tools (the status, search, and usage tools) are marked as such in the protocol, so most clients will run them without asking for approval each time. The tools that spend credits still prompt.

## How processing works

FastDrop processing is asynchronous. Submission tools return a `job_id` immediately, along with a `poll_after_seconds` hint telling the agent how long to wait before checking. The agent then polls `fastdrop.job.status` until the status is `completed` or `failed`.

Typical durations:

| Work | Rough time |
| - | - |
| Thumbnails, diagnostics, fingerprint | \~10s |
| Classification | 10-60s depending on tier |
| Clip detection | \~20s |
| Transcription | 45s+, longer for long videos |
| A 50-video batch | several minutes |

You don't need to manage any of this yourself — the agent handles polling. It's just useful to know why a request doesn't answer instantly.

## Controlling response size

`fastdrop.batch.status` accepts a `response_format` parameter:

* **`concise`** (default) — per-video status, role, confidence, and suggested filename
* **`detailed`** — everything, including thumbnail URLs, clips, and diagnostics

Concise is the default because a detailed 50-video response contains 250 presigned thumbnail URLs and can consume a large share of your agent's context window. Ask for `detailed` when you genuinely need it, or use `fastdrop.job.status` on the single video you care about.

`fastdrop.job.status` accepts the same parameter, defaulting to `detailed` since it only covers one video.

## Resources

Alongside tools, the server exposes one MCP **resource**:

| URI | Contents |
| - | - |
| `fastdrop://capabilities` | Every capability with its credit cost, plus bundles |

Clients that support resources can read this instead of spending a tool call on data that never changes.

## Example conversation

> **You:** Classify these three clips for me and tell me which ones are B-roll: [https://example.com/a.mp4](https://example.com/a.mp4), [https://example.com/b.mp4](https://example.com/b.mp4), [https://example.com/c.mp4](https://example.com/c.mp4)
>
> **AI Agent:** I'll submit those as a batch. *(calls `fastdrop.batch.classify`)*
>
> Submitted — batch `b1c2d3e4`, 6 credits. Checking back in about 30 seconds…
>
> *(calls `fastdrop.batch.status`)*
>
> All three are done:
>
> * **a.mp4** — A-Roll, 92% confidence → `AROLL_Interview_Intro.mp4`
> * **b.mp4** — B-Roll, 88% confidence → `BROLL_City_Streets.mp4`
> * **c.mp4** — B-Roll, 81% confidence → `BROLL_Office_Cutaway.mp4`
>
> So b.mp4 and c.mp4 are your B-roll.

Notice the agent never asked for an API key — it's in the header.

## Technical details

* **Endpoint:** `https://api.fastdrop.io/mcp`
* **Transport:** Streamable HTTP (POST-based JSON-RPC with SSE responses)
* **Mode:** Stateless — no session persistence, no session affinity required
* **Authentication:** `X-API-Key` header

<Note>
  The endpoint was previously documented as `https://api.fastdrop.io/mcp/mcp`. That path still works and existing configurations don't need to change, but `/mcp` is now the canonical URL.
</Note>

The MCP server calls the same REST API endpoints under the hood, so credit costs, rate limits, and capabilities are identical to direct API use.

## Testing the connection

List the available tools:

```bash theme={null}
curl -X POST https://api.fastdrop.io/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-API-Key: fd_live_your_key_here" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}'
```

A successful response lists all 12 `fastdrop.*` tools, each with a description on every parameter. Responses use `text/event-stream`, so the JSON-RPC payload arrives on a line prefixed with `data:`.

To confirm your key works, call a free tool:

```bash theme={null}
curl -X POST https://api.fastdrop.io/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-API-Key: fd_live_your_key_here" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/call",
       "params": {"name": "fastdrop.account.usage", "arguments": {}}}'
```

## Troubleshooting

<Note>
  **The agent says it needs an API key.** Your client isn't sending the `X-API-Key` header. Check that the `headers` block is inside the `fastdrop` server entry in your config, then restart the client — most only read MCP config at startup.
</Note>

<Note>
  **"FastDrop rejected the API key."** The key reached us but was invalid, revoked, or deactivated. Confirm it in the [developer portal](https://fastdrop.io/developers) and check for a stray space or a truncated paste.
</Note>

<Note>
  **"Insufficient credits."** The error states exactly how many credits the call needed versus how many you have. Reduce the number of videos, drop to `processing_tier: "basic"`, or top up.
</Note>

<Note>
  **A GET to the endpoint returns Not Found.** Expected — `/mcp` is a POST-only JSON-RPC endpoint. Use the curl commands above rather than a browser.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.