# MCP server

Framehood's primary interface is the [Model Context Protocol](https://modelcontextprotocol.io).
Any MCP-aware client can connect and use the [tools](/reference/tools) directly.

## Endpoint

```
https://mcp.framehood.ai/mcp
```

- **Transport:** Streamable HTTP
- **Auth:** OAuth 2.1 with PKCE and Dynamic Client Registration — your client
  opens a browser for sign-in on first connect; no API key to copy. Clients that
  can't run the browser OAuth flow (Claude Code with `--header`, the Claude API
  MCP-connector, or a Slack/Claude Tag plugin) can instead send a Framehood API key
  as `Authorization: Bearer <key>` — see [API key (Bearer header)](#api-key-bearer-header).

## Connect a client

### Claude.ai (web & desktop app)

Add Framehood as a custom connector in [claude.ai](https://claude.ai): **Settings
→ Customize → Connectors → + → Add custom connector**, paste
`https://mcp.framehood.ai/mcp`, then **Connect** and approve the browser sign-in.
See the illustrated, step-by-step [Add to Claude.ai](/guide/claude-ai) guide.

### Claude Code

```sh
claude mcp add --transport http framehood https://mcp.framehood.ai/mcp
```

Then run `/mcp` inside Claude Code and complete the browser sign-in. Or install
the [Claude Code](/guide/plugin) plugin, which bundles this server.

### Claude Desktop

Settings → **Connectors** → **Add custom connector**, then enter:

- **Name:** Framehood
- **URL:** `https://mcp.framehood.ai/mcp`

Approve the browser sign-in when prompted.

### Cursor

Add to `~/.cursor/mcp.json` (or the project's `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "framehood": {
      "url": "https://mcp.framehood.ai/mcp"
    }
  }
}
```

### ChatGPT

In ChatGPT (Developer Mode / connectors), add a custom connector and point it at
`https://mcp.framehood.ai/mcp`, then approve the browser sign-in. The toolset
is identical to any other client, but ChatGPT's MCP client has a few
behavioral differences — file parameters, media previews, polling, and
notifications — see [ChatGPT / OpenAI MCP compatibility](/guide/chatgpt).

### Generic MCP client

Any client that supports remote (HTTP) MCP servers with OAuth works. Configure:

```json
{
  "mcpServers": {
    "framehood": { "type": "http", "url": "https://mcp.framehood.ai/mcp" }
  }
}
```

### API key (Bearer header)

For clients that can't complete the browser OAuth flow — Claude Code with a
`--header` flag, the Claude **API MCP-connector**, or a **Slack / Claude Tag**
plugin — authenticate with a Framehood API key (mint one from the API-keys page or
`api_keys(create)`) sent as an `Authorization: Bearer <key>` header:

```sh
claude mcp add --transport http framehood https://mcp.framehood.ai/mcp \
  --header "Authorization: Bearer <your-framehood-api-key>"
```

For a **Slack / Claude Tag** plugin, point a plugin's `.mcp.json` at
`https://mcp.framehood.ai/mcp` and store the key as a **Bearer credential** in the
workspace's access bundle (allowed website `mcp.framehood.ai`) — the proxy attaches
the header for you, so the key never goes in the plugin file. See the step‑by‑step
[Framehood in Slack (Claude Tag)](/guide/slack) guide.

An API-key session has the same access as your account **except** it can't manage
API keys (mint or revoke) — that still requires a browser/OAuth sign-in.

## First steps after connecting

1. Call a tool, e.g. `image` with `{ "action": "create", "prompt": "…", "out": "hero.jpg" }`.
2. If the response is a queued job, poll `get_status(job_id=…)` until it
   succeeds; the output URL is in `outputs`.
3. To transcribe an audio or video URL into timecoded segments, call
   `qa(action="transcript", video=…)` (or `audio=…` for a pure audio file).

See the full [tools reference](/reference/tools) for the complete toolset.

## Notes

- The OAuth issuer is the connection host (`mcp.framehood.ai`), so tokens are
  scoped to this server.
- Inside an organization, members without payment access can call
  `billing(request_upgrade)` to email the owner; owners get payment and
  org-management tools.