# fathom-mcp-adapter

Read-only MCP server that exposes Fathom meetings + transcripts as tools, for use
by `/updateP1` (and other skills) in the TICKETS workspace.

This is a **private, standalone** adapter: its own git repo, its own `.env`. It is
**not** part of `ia-tooling` and does not depend on its stack — it only makes HTTPS
calls out to the Fathom REST API (`https://api.fathom.ai/external/v1`). It was scaffolded by
cloning the structure of `ia-tooling/services/zendesk-mcp-adapter`.

## Architecture

The adapter *is* the MCP server. Internally it calls the **Fathom REST API**
directly (just as the Zendesk adapter calls Zendesk's REST API). MCP servers are
not chained to one another.

- Auth: per-user API key sent as the `X-Api-Key` header. The key is scoped to one
  user (their own meetings + meetings shared to their Team), which provides data
  isolation between teammates. Rate limit: 60 req/min.
- The adapter returns the **raw** transcript. The who/what/when summary is produced
  by the `/updateP1` skill, never by a tool here.
- There is **no title/keyword search** in the Fathom API. To find a specific
  meeting, list recent meetings (optionally narrowing by `created_after` /
  `recorded_by`) and let the skill filter by title/date/invitee.

## Tools

| Tool | Purpose |
| --- | --- |
| `fathom_health` | Config/connectivity check (makes one authenticated call). |
| `fathom_list_recent_meetings` | List recent meetings, newest first. Filters: `created_after`, `created_before`, `recorded_by`, `invitee_domains`, `meeting_type`. |
| `fathom_get_latest_meeting` | The single most recent meeting (the 90% case for `/updateP1`). |
| `fathom_get_transcript` | Raw transcript for a `recording_id`. |

Each meeting record includes `title`, `recording_id`, `created_at`, `url` (private,
login-gated) and `share_url` (team-shareable). For the internal timeline reference
use **`share_url`**, never `url`.

## Setup

```bash
npm install
cp .env.example .env   # then fill in FATHOM_API_KEY
npm test
npm start              # speaks MCP over stdio
```

`FATHOM_API_KEY` must come from `.env` (which is git-ignored) — never hardcode it.

## Wiring into the TICKETS MCP session

Build the image and add a `fathom` entry to the TICKETS `.mcp.json`, alongside
`zendesk` / `vectordb` / `github`. It does not need the `ia-tooling_default`
network (HTTPS egress only).

```bash
docker build -t fathom-mcp-adapter .
```

```jsonc
// .mcp.json (TICKETS)
{
  "mcpServers": {
    "fathom": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "--env-file", "/ABSOLUTE/PATH/TO/.env", "fathom-mcp-adapter"]
    }
  }
}
```

## Fallback

If the Fathom MCP server is down, `/updateP1` falls back to the manual
"paste-me-the-transcript" mode rather than blocking (same pattern as
zendesk/vectordb).