# Circleback — MCP transcript ingest reference

Companion to [`conversation-archive-mcp`](../../skills/conversation-archive-mcp/SKILL.md). Names the install command, the expected MCP tool surface, the returned shape, and how to map that shape into `memory-ingest` parameters for the conversation-archive writer.

## Install (operator)

Circleback ships a remote streamable-HTTP MCP server at `https://circleback.ai/api/mcp`. Install once per Claude Code host:

```bash
claude mcp add --transport http circleback https://circleback.ai/api/mcp
```

Circleback also ships a CLI, but the MCP path is the canonical surface for this skill — the CLI is operator-side only. First invocation opens an OAuth flow in the operator's browser; the operator authorises which meetings Circleback exposes to this Claude Code session. Tokens live in the host, not in maxy.

**Operator-facing verification.** After install, run `/mcp` in admin chat. The expected entry is `circleback — connected` with a tool count > 0. If the entry is missing or shows an error, re-run the install one-liner before invoking the ingest skill.

## Expected tool surface

The skill discovers tools by name pattern at run time. Expected tools (names may drift):

- **List meetings.** Pattern: `mcp__circleback__list_meetings`, `mcp__circleback__search_meetings`, or similar. Accepts a date window and/or text filter; returns an array of meeting objects with at minimum `id`, `title`, `startedAt`, `attendees`.
- **Fetch a meeting's transcript.** Pattern: `mcp__circleback__get_meeting`, `mcp__circleback__read_meeting`, or similar. Accepts a meeting ID; returns the full meeting including the transcript turns.

If discovered tools diverge, match by description. Run `/mcp` to enumerate the live set.

## Returned shape (typical)

A Circleback meeting object carries the following fields relevant to ingest:

| Circleback field | Maps to memory-ingest |
|---|---|
| `id` / `meetingId` | `circlebackMeetingId` (cross-reference property on `:ConversationArchive`) |
| `title` | `archiveTitle` (prefixed with `"circleback · "` and suffixed with the ISO date) |
| `startedAt` / `start_time` | `lastIngestedMessageAt` fallback when transcript turns lack per-turn timestamps |
| `attendees[]` — each with `name`, `email` | Per-attendee resolution against `:AdminUser` / `:Person` (Step 4 of the skill) |
| `transcript[]` — each with `speaker`, `timestamp`, `text` | Rendered into turn-attributed `[<ISO>] <speaker>: <text>` lines for the typed-section JSON |
| `calendarEventId` / `event_id` | `calendarEventId` cross-reference property on `:ConversationArchive` when present |
| `actionItems[]` / `summary` | NOT used for `:Section` rows — provider-authored layers; downstream Phase 2 derivation produces uniform typed claims from the transcript |

## Edge cases

- **Meeting with multiple recording segments** — Circleback occasionally splits a single meeting across two recording sessions (e.g. operator paused recording mid-meeting). The MCP `list_meetings` tool returns them as two distinct meeting IDs. Each ingests as its own `:ConversationArchive`. Cross-segment dedup is not in scope.
- **Attendee with no email** (Circleback often resolves names from calendar invites but may carry free-text additions): falls through to the per-attendee prompt loop.
- **Redacted transcripts** — Circleback supports operator-side redaction. Redacted spans render as `[REDACTED]` in the turn text; the skill writes them as-is. The downstream classifier treats them as ordinary tokens.

## What this reference is not

- Not a Circleback API or CLI reference. The MCP surface is the contract for this skill.
- Not a token manager. OAuth is in the host.