> For the complete documentation index, see [llms.txt](https://getsquish.gitbook.io/squish/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://getsquish.gitbook.io/squish/reference/remote-mcp.md).

# Remote MCP endpoint

`https://api.getsquish.app/mcp` — the same engine as the [MCP server](/squish/reference/mcp.md), spoken over the official MCP **Streamable HTTP** transport. It exists for AI apps that only take a connector URL (Claude Desktop, claude.ai custom connectors): no install, no local ffmpeg.

Unlike the local server, this endpoint runs on Squish's hosted infrastructure: the video is fetched **from a public URL** by the endpoint — nothing uploads from your machine — and the sheets are served from short-lived capability URLs. See [Privacy and data flow](/squish/the-primitive/privacy-and-data-flow.md) for the full split.

## Setup (Claude Desktop / claude.ai)

1. Settings → Connectors → **Add custom connector**
2. Name: `Squish`
3. URL: `https://api.getsquish.app/mcp` — no key needed; the consumer connector dialog rides the anonymous free lane (its advanced settings take OAuth only). On Claude Team/Enterprise an org admin can attach an API key as a fixed request header when adding the connector (Anthropic's `static_headers` beta) — that unlocks the keyed lane below for the whole org.
4. In a chat: enable Squish under Connectors, then ask about any public video URL

## The tool

The same single tool, `squish_video`, with remote ends — its own contract string, `squish-mcp-http-v0`:

| Parameter       | Difference from the [local server](/squish/reference/mcp.md#parameters)                                                                            |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `video_url`     | Replaces `video_path`: a public http(s) URL of a **direct video file** (not a YouTube/streaming page). Private and internal addresses are refused. |
| `density`       | Identical.                                                                                                                                         |
| `start` / `end` | Identical — the [navigation loop](/squish/the-primitive/the-navigation-loop.md) works from official apps, timecodes absolute at every depth.       |
| `out_dir`       | Not available — the server owns output placement.                                                                                                  |

On success the result is one JSON text block — the local result shape with `files[]` as **\~24 h capability URLs**, plus `sheet_ttl_hours` and `job_id` — and the first sheet attached as an inline MCP image block.

## The inline thumbnail always ships

Official apps cap the total size of a tool result, and models inside official apps generally **cannot fetch the capability URLs themselves** — the inline image is the model's only eyes. So the endpoint re-encodes the first sheet down a quality/size ladder until it fits the budget (\~90 KB): easy content arrives crisp; high-detail content arrives as a smaller thumbnail plus a warning telling the model to read exact labels from `timecodes[][]` (cells run left→right, top→bottom — the JSON and the pixels never disagree). A zoomed follow-up call narrows the window, which raises the thumbnail's effective resolution — the loop self-heals.

## Transport shape

Stateless and POST-only: `GET`/`DELETE` answer `405` (spec-compliant for a server that opens no streams), responses are plain JSON, and no `Mcp-Session-Id` is ever issued. Host and Origin headers are validated.

## Authentication & quotas

The endpoint has two lanes:

* **Keyed** — send `Authorization: Bearer sq_live_…` with the same API key the [HTTP API](/squish/reference/http-api.md) uses, minted at [getsquish.app/api-keys](https://getsquish.app/api-keys) (revoke/rotate on the same page: create a new key, revoke the old). Requires a client that can send the header — Claude Code (`claude mcp add --transport http squish https://api.getsquish.app/mcp --header "Authorization: Bearer sq_live_…"`), `mcp-remote`, any SDK client, or an official-app connector whose Team/Enterprise org admin attached the key as a request header (`static_headers`, beta); the consumer connector dialog is OAuth-only. Jobs are priced in the same [density-weighted credits](/squish/reference/http-api.md#credits-and-pricing) as `POST /v1/squish` — charged before extraction, **auto-refunded** if the engine fails — and each job appears in the usage table on `/api-keys`. Successful results carry `credits_charged` and `credits_remaining`.
* **Anonymous** — no header at all. A small free lane: a few jobs per UTC day (currently 3), counted per user when the client sends the Apps-SDK `_meta["openai/subject"]` id (official AI apps reach this endpoint through shared egress IPs) and per IP otherwise, under a shared endpoint-wide daily ceiling. Successful results carry `free_jobs_remaining_today`. When the lane runs out, the tool returns a **structured JSON error** the model can relay. On most lanes it carries `billing_url` and a hint — mint a free key (7 free credits/day, no card) or run Squish locally. **Apps-SDK (ChatGPT app) traffic hears a non-commercial version instead** — wait for the 00:00 UTC reset or run Squish locally — because OpenAI's app-guidelines forbid digital-credit upsells (including freemium ones) inside ChatGPT apps.

A present-but-invalid `Authorization` header is an honest `401` (never a silent downgrade to the free lane). Request floods answer `429` with a `Retry-After` header.

## Beta limits

Abuse is bounded by the lanes above plus a one-video-at-a-time gate (a busy call returns a polite retry message, never a hang). Fetched videos obey the hosted caps (300 MB / 30 min) and are deleted when the job ends; sheets expire after \~24 h.

## When to prefer it

* The client is an official AI app that only takes a connector URL → this endpoint.
* The agent has a shell or filesystem (Claude Code, Cursor, Hermes, any stdio client) → the [local MCP server](/squish/reference/mcp.md): on-device, free, no upload, no caps.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://getsquish.gitbook.io/squish/reference/remote-mcp.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.