calaf-mcp

# Calaf MCP Server

Connect Claude, ChatGPT, or any MCP-capable assistant to [Calaf](https://calaf.ai) — the MBA recruiting manager. Your assistant researches target firms at whatever depth you ask, writes and validates structured "seeds," and files them into your recruiting book. People it proposes always arrive **staged for your review** — nothing enters your network behind your back.

[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-ai.calaf%2Fcalaf-blue)](https://registry.modelcontextprotocol.io)
[![Listed on mcpservers.org](https://mcpservers.org/badge.svg)](https://mcpservers.org/servers/calaf-ai-connect-md)
[![Setup Guide](https://img.shields.io/badge/setup-calaf.ai%2Fconnect.md-green)](https://calaf.ai/connect.md)
[![Seed Format](https://img.shields.io/badge/format-calaf.ai%2Fseed--format.md-green)](https://calaf.ai/seed-format.md)

> **Two servers, one product.** `ai.calaf/calaf` connects to your account (OAuth). `ai.calaf/seeds` is the no-auth authoring loop — the format and the validator, usable by anyone, no Calaf account required.

| Server | Endpoint | Transport | Auth |
| --- | --- | --- | --- |
| **Calaf** | `https://calaf.ai/api/mcp-account` | Streamable HTTP | OAuth 2.1 (dynamic client registration) |
| **Calaf Seed Tools** | `https://calaf.ai/api/mcp` | Streamable HTTP | None |

## Things to ask once connected

- *"Research 30 lower-middle-market PE funds that hire MBA associates, validate the seed, and import it into my book."*
- *"Read Calaf's seed format, then turn the target list from this conversation into a seed and validate it until it's clean."*
- *"List my Calaf workspaces and import these interview prep questions into the consulting one."*
- *"I just got off a superday with Evercore — log it, move my application, and set a follow-up task for Friday."*
- *"Create a workspace for lower-middle-market PE, add my ten targets, and draft outreach templates."*
- *"Research the partners at my five priority funds and add them to my book"* — they'll land as a **batch waiting for your review** in Calaf, never as silent rows.

## Installation

### claude.ai (web / desktop)

1. Open **Settings → Connectors** ([claude.ai/settings/connectors](https://claude.ai/settings/connectors))
2. **Add custom connector** → name it `Calaf`, URL `https://calaf.ai/api/mcp-account`, leave Client ID/Secret empty
3. Click **Connect** → you'll land on Calaf's consent screen — sign in and approve

*Requires a paid claude.ai plan (custom connectors are Pro and above).*

### Claude Code

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

### Any other MCP client

Add a remote (Streamable HTTP) server at `https://calaf.ai/api/mcp-account`. The OAuth flow is standard: dynamic client registration + PKCE; your client discovers the authorization server via RFC 9728 protected-resource metadata.

### No MCP client at all

The copy-paste loop works with every assistant: Calaf's [Guide](https://calaf.ai/guide) and Settings carry a one-paste prompt that teaches any AI the [seed format](https://calaf.ai/seed-format.md); the assistant can self-check via the open validator API (below) and you import the file at **Settings → Workspace → Seeds**.

## Tools — `ai.calaf/calaf` (account server)

### `get_seed_format` · read-only

Returns the complete `calaf_seed: 1` specification (markdown) — sections, ceilings, parser behavior, and the rules an assistant should follow when authoring a seed. Read it before authoring; then check drafts with `validate_seed`.

*No parameters.*

### `validate_seed` · read-only

Runs a draft seed document through **the exact parser the Calaf app imports with** and returns the verdict: per-section counts plus the precise issue list. Issue severity `error` means nothing would import; `dropped` means that row or field is discarded and the rest lands. Fix and re-validate until clean before delivering the file.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `seed` | string \| object | yes | The complete seed JSON document — as text, or as the JSON object itself |

**Returns** (structured): `valid`, per-section `counts` (orgs, contacts, templates, prep, keyDates, orgKinds, ladderRungs), `hasVocab`, `hasPlanner`, and `issues[]` with `path` (e.g. `orgs[3].name`), `message`, `severity`.

### `list_workspaces` · read-only

Lists the caller's Calaf workspaces — key, display name, position. Use the key as the `workspace` argument to `import_seed`.

*No parameters.* **Returns**: `workspaces[]` with `key`, `name`, `emoji`.

### `import_seed` · write (non-destructive, idempotent)

Imports a valid seed into one of the caller's workspaces — the same landing the app's import performs:

- **Organizations** — deduped account-wide by name, then joined to the workspace
- **Templates** — deduped within the workspace
- **Prep questions** — deduped account-wide
- **People — never written directly.** Contacts in the file are **staged as a reviewable batch** in Calaf: the user accepts, trims, or discards them together, and can undo an accepted batch in one click. A person must name an org to be stageable.

Re-importing the same file lands nothing twice; nothing is ever deleted or overwritten.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `workspace` | string | yes | Workspace key, from `list_workspaces` |
| `seed` | string \| object | yes | The complete seed JSON document |
| `parts` | string[] | no | Which parts to process: `orgs`, `templates`, `prep`, `contacts` (= stage people). Defaults to everything the file carries |

**Returns** (structured): `ok`, `landed` (counts per part), `failed[]`, and `staged` — `people`, `orgs`, `buildId`, `skippedWithoutOrg`, `skippedInvalid`.

### `export_seed` · read-only

Serializes a workspace back into a `calaf_seed` document — the reverse loop: read the book, improve it, re-import (dedupe means a round trip never doubles anything). **Privacy defaults**: people, the user's personal notes, and content that arrived from other seeds stay out unless explicitly requested (`include_people`, `include_notes`, `include_seeded`); withheld and ceiling-truncated counts are always reported. No plan gate — data portability never sits behind a paywall.

### `get_profile_schema` / `get_firm_profile` / `submit_firm_profile`

Firm research at house depth. `get_profile_schema` returns the module shapes (overview, hq, leadership, comp, process, culture/recruiting notes) **and the sourcing epistemics a submission must meet** (MBA-grade comp sources, null beats a guess, verify leadership at the source). `get_firm_profile` reads current state with per-field provenance so chat edits merge against reality. `submit_firm_profile` writes sourced modules into the user's own overlay — rendered on their firm page badged as assistant research — under the merge contract: **empty fields fill, fields the assistant wrote refresh, fields the user typed are never overwritten** (reported as conflicts), and `clear` removes only assistant-owned fields. Sources are required; claims without them drop wholesale.

### `log_touchpoint` · write

Records an interaction (coffee chat, email, event, reply…) with the app's own automations: contact status ladder (never downward), optional follow-up scheduling (which lands on the user's calendar), optional next-day thank-you task, and waking a Researching firm to Networking on real activity.

### `update_contact` · write

Completes a person **already in the book**. Identity fields (email/phone/LinkedIn/school/title/group) fill only where empty — user values win, differences reported. Relationship facets (warmth 1–5, stage, next follow-up, connection type) set explicitly, because "mark Jane dormant" is the ask itself. A firm link fills only when the person has none. `append_note` adds a dated, attributed note under — never over — the user's own. Creating people stays behind `import_seed`'s staged review.

### `add_task` · write

A due-dated task, optionally tied to a contact or firm. Tasks, follow-ups, and deadlines are what the user's calendar renders — this is the assistant's path onto it.

### `get_contacts` / `get_firms` · read-only

Paged summaries (contacts include which detail fields are still empty — worth researching) so the assistant navigates the real book, not its memory of it.

### `log_firm_work` / `get_firm_work` / `remove_firm_work` · work log

The deals and work items coffee-chat talking points are made of. `log_firm_work` adds one to a firm's work log with sourcing facets (where it came from, how solid it is: Confirmed / Reported / Rumored); `get_firm_work` reads the log back, marking which rows are assistant-logged. `remove_firm_work` deletes **only items the assistant itself wrote** — entries the user logged by hand are refused, the same class of guarantee as the staged-people rule.

### `get_applications` · read-only

The recruiting pipeline: each application's firm, program, status, deadline, and next interview date.

### `schedule_interview` · write

Puts an interview round on an application's timeline — and so on the user's calendar. Works forward (scheduled) or backward (`completed: true` with an outcome). Every save also runs the app's own sync: the application's next-interview date recomputes and its status advances along the workspace's real stage ladder (never downgrading, never reopening a closed outcome).

### `add_application` / `update_application` · pipeline

`add_application` opens a pipeline row (firm + program; defaults to Watching; duplicates refused). `update_application` moves it the way the app's board does — status changes append to the stage history and backfill the applied date — and records outcomes (`offer_accepted` / `offer_declined` / `rejected` / `withdrawn`). Offered comp figures **fill only where the user hasn't entered their own**; differences are reported, never applied.

### `get_tasks` / `complete_task` / `snooze_task` · the to-do loop

List task