Arcmira MCP

Name: mcp
Author: arcmira

Arcmira is an SF-based AI company and the search engine for the spoken web.

This is the official Arcmira MCP server. It gives Claude, Cursor, ChatGPT, and any MCP client eight read-only tools over indexed YouTube and podcast transcripts: what a show said, the full transcript of one video, who was mentioned where, momentum, sponsors, and coverage. It is a stateless facade over the public HTTP API at https://api.arcmira.com/v1; every gate the API raises is forwarded untouched with the link that lifts it.

Endpoint: https://mcp.arcmira.com/mcp (Streamable HTTP)
Registry name: io.github.arcmira/arcmira
Docs: https://arcmira.com/docs
HTTP API the tools front: https://api.arcmira.com/v1/openapi.json

Connect

Two ways in. Hosts that speak the MCP authorization spec sign you in; everything else sends a key.

Sign in through the host. Add https://mcp.arcmira.com/mcp with no key. The server answers 401 with an OAuth challenge, the host registers itself against api.arcmira.com, opens arcmira.com for sign-in and consent, and connects with a token that carries the permissions you allowed. Tokens refresh on their own; revoke a host under Settings, Connected apps.

claude mcp add --transport http arcmira https://mcp.arcmira.com/mcp

Claude Desktop, claude.ai, ChatGPT, and Cursor: add the URL as a custom connector or MCP server with no headers and follow the sign-in prompt.

Send a key. Any client that cannot do the sign-in sends a bearer token instead, and the server skips OAuth:

An account key (arc_sk_...) from https://arcmira.com. Plan and scopes decide what each tool returns.
A trial key (arc_tk_...), minted with no login. It reads exactly what a free account reads, with a smaller row allotment and a 7 day expiry:

curl -X POST "https://api.arcmira.com/v1/trial-keys?src=mcp-tool"

claude mcp add --transport http arcmira https://mcp.arcmira.com/mcp --header "Authorization: Bearer $ARCMIRA_API_KEY"

{
  "mcpServers": {
    "arcmira": {
      "url": "https://mcp.arcmira.com/mcp",
      "headers": { "Authorization": "Bearer arc_tk_..." }
    }
  }
}

The 401 body carries the same mint call under error.data.unlock.action, so an agent that cannot sign in can get its own trial key and reconnect. Discovery: https://mcp.arcmira.com/.well-known/oauth-protected-resource names the authorization server; https://api.arcmira.com/.well-known/oauth-authorization-server lists its endpoints.

Tools

Tool	Use it for	Fronts
`resolve_entities`	Turn a name, `@handle`, YouTube URL, or `UC` id into typed `ent_` rows	`GET /v1/entities/search`
`search_transcripts`	Short spoken slices for one topic, with watch links and dates	`GET /v1/transcripts/search`
`list_mentions`	Has X mentioned Y yet, first seen, last seen	`GET /v1/mentions`
`entity_momentum`	Mentions in the last 7 and 30 days against the prior 30, with a verdict	`GET /v1/entities/{id}/momentum`
`count_occurrences`	What a set of shows talks about, and what they share	`GET /v1/mentions/counts`
`list_sponsors`	Recurring sponsors of a channel from the ad-read rollup	`GET /v1/channels/{id}/sponsors`
`index_status`	What the index holds for a channel, or one transcription job	`GET /v1/channels/{id}/coverage`, `GET /v1/transcriptions/{id}`
`get_transcript`	Full transcript of one video from its URL or id, with `start` on every line	`GET /v1/transcripts/{video_id}`, `GET /v1/videos/{video_id}/captions`

Every tool declares readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false. Every result carries as_of where a date applies and a one-sentence note.

Good first calls: TBPN is channel UC-DRzaGnL_vtBUpCFH5M0tg, Moment of Truth is UClWkDGXEzsh77GAhs90wpXw, Ramp is ent_14.

Gates

A gate is an MCP tool result with isError: true whose content is the API's error envelope:

{
  "error": {
    "type": "permission_error",
    "code": "filter_requires_paid",
    "message": "The source filter needs Hobby.",
    "param": "source",
    "gate": "plan",
    "unlock": { "tier": "hobby", "url": "https://arcmira.com/pricing?src=mcp-tool", "offer": null },
    "doc_url": "https://arcmira.com/docs/errors#filter_requires_paid",
    "request_id": "req_..."
  }
}

Switch on error.code, relay error.unlock.url to the human, and honor retry_after_seconds on rate_limited. A 200 that withheld something (Premium transcript text, the paid-versus-organic split, sponsors past the free slice) is a normal result carrying the same body under access. The full catalog is at https://arcmira.com/docs/errors.

Develop

pnpm install
pnpm dev            # wrangler dev on :8790, API base from .dev.vars
pnpm test           # node:test
pnpm typecheck
pnpm manifest:check # every tool call matches the live OpenAPI document
ARCMIRA_KEY=arc_tk_... node --experimental-strip-types scripts/smoke.ts http://localhost:8790/mcp

The tool descriptions are loaded context and are the steering surface. They are maintained in Arcmira's manifest spec first and copied here verbatim; revise there before here.