arcmira

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

The official Arcmira MCP server. Nine read-only tools over indexed YouTube and podcast transcripts: the full transcript of one video, the newest episodes of a show, what a show said, who was mentioned where, momentum, sponsors, and coverage. One remote URL, sign in through your host or send a key, or mint a free trial key with no account.

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
• Install guide: https://arcmira.com/docs/mcp
• Server card: https://mcp.arcmira.com/.well-known/mcp/server-card.json
• 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

codex mcp add arcmira --url 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. Per-host steps are on https://arcmira.com/docs/mcp.

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; videoIds scopes it to one episode	GET /v1/mentions/counts
list_episodes	The newest indexed episodes of one channel, with the video_id the other tools take	GET /v1/channels/{id}/videos
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, as text 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. Seven of the tools return the JSON body in both the content block and structuredContent. get_transcript returns the transcript itself as text in the content block, and structuredContent carries the metadata without the lines, so a long transcript crosses the wire once.

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.

Every result, gates included, carries the key's budget after the call under _meta["arcmira.com/rate_limit"] as { "limit": 20, "remaining": 17, "reset": 1788819360 }, read from the API's RateLimit headers. reset is Unix seconds at the next window. Hosts do not show _meta; a client that watches its spend reads it there.

Every result also carries _meta["arcmira.com/build"]: server (this server's version), deploy (its Worker deploy id), api (the deploy id of the API build that answered, from the X-Arcmira-Build response header), and client (the host's name and version from its initialize handshake, which the server forwards to the API as x-arcmira-client). A transcript a host keeps can be joined to the exact code that produced it.

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
ARCMIRA_KEY=arc_tk_... node --experimental-strip-types scripts/measure-transcript-bytes.ts <video-id> 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.

Copyright Arcmira. All rights reserved. See LICENSE.