Vet Ready exposes your clinic data through an **MCP server** (Model Context Protocol) so AI assistants like Claude Code, Claude Desktop, Cursor, and VS Code can read and act on your organization's data directly. Ask questions like *"show me today's schedule"* or *"which clients still need to finish their prep"* and the AI pulls the data in real time.

## What is MCP?

MCP (Model Context Protocol) is an open standard for AI assistants to connect to external data sources. Instead of copying data into a chat window, the AI tool connects to Vet Ready's MCP server and reads the data it needs for each question.

## How to connect

Vet Ready implements the official OAuth 2.1 authorization flow that the MCP spec requires. There are **no API keys to manage and no tokens to copy/paste**. The first time you connect, your AI client opens a browser, you sign in to Vet Ready (or you're already signed in), approve the scopes the client is asking for, and you're done. The consent screen lives at `auth.vetready.ai` — a dedicated origin specifically for authorization, so you always know where you're approving access from.

### Claude Code

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

Then run `/mcp` inside Claude Code. The first tool call opens a browser window — sign in with Google, approve the scopes, pick your organization if you belong to more than one, and close the tab. Subsequent sessions re-use the grant until you revoke it or your refresh token expires.

### Cursor / VS Code with MCP support

Configure the server URL as `https://mcp.vetready.ai`. Leave the **Authorization** field blank — the client handles auth itself via the OAuth flow. Cursor and VS Code implementations of MCP both support Dynamic Client Registration; no setup in the Vet Ready dashboard is required.

### Claude Desktop

Add the server to your Claude Desktop MCP settings with URL `https://mcp.vetready.ai`. Claude Desktop prompts you to sign in the first time you use it.

### Client identification

Vet Ready accepts **two** registration mechanisms side-by-side — you don't pick, the client does:

- **DCR (Dynamic Client Registration, RFC 7591)** — the historical path. The client POSTs to `/oauth/register` to mint an opaque `client_id`. All current MCP clients that don't support CIMD still work this way.
- **CIMD (Client ID Metadata Documents, MCP 2025-11-25)** — the newer path. The client presents an `https://…` URL as its `client_id` and Vet Ready fetches + validates the metadata document at that URL. No registration round-trip, no re-register after a long idle period. Claude Code and Claude Desktop are rolling out CIMD support; when they flip, re-auth becomes a single tap instead of a full DCR handshake.

## What the AI can do

When your client connects, it sees a catalog of **61 tools** organised by pool (clinic vs. pet-owner) and scope (read vs. write). Most are 1:1 mirrors of the REST API; five are **intent-grouped workflows** that compose 2–4 primitives into a single round-trip the AI can call once instead of stitching the primitives itself.

### Intent-grouped workflow tools (clinic + consumer)

The five highest-value workflows live here. Each returns a `next_steps` array telling the AI what to chain next — so a vet saying *"run the morning huddle"* gets a single tool call with everything needed, not a dozen.

| Tool | Pool | What it does |
| --- | --- | --- |
| `prepare_clinic_day` | clinic | Schedule + recently flagged intakes + team roster, in one call. Backs the "morning huddle" skill. |
| `review_intake_and_respond` | clinic | Behaviour profile + plan + transcript + prep progress for a single session, in one call. |
| `onboard_clinic` | clinic | Destructive — creates org + default clinic + invitations + flow-template catalog. Requires explicit confirmation. |
| `find_client` | clinic | Fuzzy-search across owner email/name + dog name within this org. |
| `enrol_dog_for_visit` | consumer | Create/reuse dog + book appointment + start intake in one call. |

### Clinic (platform) tools

Read tools include `get_my_platform_profile`, `get_org`, `list_org_members`, `list_org_clinics`, `list_intake_summaries`, `get_intake_summary`, `get_intake_progress`, `get_intake_transcript`, `list_org_clients`, `get_schedule` (the Today view), `list_flows`, `list_flow_templates`, `list_invitations`, `get_billing`.

Write tools (require the `mcp:platform:write` scope at consent time) include `create_org`, `update_org`, `update_member_role`, `remove_member`, `create_invitation`, `revoke_invitation`, `accept_invitation`, `create_clinic`, `update_clinic`, `delete_clinic`, `create_flow`, `update_flow`, `delete_flow`.

### Pet-owner (consumer) tools

Read + write tools for your own profile, dogs, intakes, appointments, preparation modules, and card-deck engagement.

All tools respect the same role rules as the web dashboard: a **member** can read the org but can't change settings; an **owner** can do everything; the clinic boundary is enforced on every call.

## Safety gates on destructive tools

Five tools permanently affect state: `delete_my_account`, `remove_member`, `revoke_invitation`, `delete_clinic`, `delete_flow`. All five use a **two-call confirm pattern**:

1. First invocation returns `{ confirmation_required: true, warning, retry_hint }` with a clear description of what will happen. The AI surfaces the warning to you.
2. Only after you explicitly confirm does the AI re-call the tool with `confirm: true`, which then executes.

Agents that don't support the pattern (or that somehow skip the confirmation) cannot execute the destructive action — the server enforces it. The `onboard_clinic` workflow also uses this pattern because it creates billable state.

## Rich inline cards (MCP Apps)

Four read tools — `get_intake_summary`, `review_intake_and_respond`, `get_schedule`, `get_billing` — return **both** JSON and a self-contained HTML card. Clients that support the MCP Apps extension (Claude Desktop, claude.ai) render the card inline in chat: the behaviour profile shows up as a colour-coded pill card, the schedule as a per-clinic timeline, billing as a status + seats + clinics tile. Clients that don't support MCP Apps see the same JSON as before — no regression.

## Pagination + rate limits

Every list tool paginates via `{ limit (1–100, default 25), cursor }`. Responses include `{ items, next_cursor }`. If the AI asks for "all my clients" on an org with 5,000 pet parents, it walks the cursor one page at a time instead of blowing a token budget.

Rate limits protect against runaway agents:

- **60 calls/min per user per tool**
- **10,000 calls/day per user** (runaway-loop ceiling)
- **2,000 write calls/hour per org**
- **50 destructive calls/hour per org**

Hitting a limit returns a structured error with `retry_after_s` so the AI knows to back off. Normal usage stays well below these.

## Security model

1. **OAuth 2.1 with PKCE, DCR + CIMD** — the same industry-standard flow used by Linear, GitHub, and other modern MCP servers. Consent happens on the dedicated `auth.vetready.ai` origin.
2. **Scoped access** — at consent time you see and approve exactly what the AI client is asking for. The four scope values in plain English:
   - `mcp:platform:read` — Read your clinic's intake summaries, clients, and schedule.
   - `mcp:platform:write` — Create invitations and manage clinics, flows, and settings.
   - `mcp:consumer:read` — Read your pet owner profile, dogs, and intake history.
   - `mcp:consumer:write` — Create dogs, appointments, and mark preparation steps complete.
3. **Short-lived tokens** — access tokens are valid for one hour, then the client silently refreshes. If the DB is ever leaked, existing tokens expire fast.
4. **Audience-bound tokens** — every access token carries `aud: https://mcp.vetready.ai` and the MCP server rejects tokens issued for any other audience.
5. **Server version advertised** — the MCP server tells every connecting client its version (`1.4.0` at time of writing) so clients can adapt if a future catalogue bump changes behaviour.
6. **No password sharing** — the AI client never sees your password. It only ever holds a scoped OAuth token for Vet Ready specifically.
7. **Revoke any time** — see **[Connected Apps](/docs/connected-apps)** for the one-click revoke UX.

## Claude Skills

Four Claude Skills ship alongside the MCP server. A Skill is a `SKILL.md` file with procedural instructions that teach Claude *how* to combine the MCP tools into a real veterinary workflow. Drop one into Claude Code's `~/.claude/skills/` (or upload via the claude.ai UI) and Claude auto-picks it when the user's intent matches:

- **`pre-surgical-intake`** — consumer booking flow on top of `enrol_dog_for_visit`.
- **`onboard-new-clinic`** — platform setup, destructive two-call confirm.
- **`review-todays-caseload`** — morning huddle with a triage rubric (safety-flagged → high-fear → first-of-day).
- **`reconcile-billing`** — read-only billing brief with anomaly detection.

## Example questions

- "Show me today's schedule." *(`get_schedule`, rendered inline as a timeline if your client supports MCP Apps)*
- "Run the morning huddle for Westside Vet." *(`prepare_clinic_day` → `review_intake_and_respond` on any flagged cases)*
- "Which dogs coming in tomorrow have high stress flags?"
- "Find Bella." *(`find_client`)*
- "Walk me through session abc123." *(`review_intake_and_respond`, renders the intake dashboard inline)*
- "Invite `colleague@clinic.com` as an admin."
- "Create a new flow for senior-wellness visits from our Puppy First Visit template."
- "Book Max in for Thursday at 2pm." *(`enrol_dog_for_visit` on the consumer side)*

## What if something feels off?

- **"I didn't recognize the app name at consent."** Hit **Cancel**. Only approve clients whose name matches what you expect to see. Treat the consent screen like a bank's 2FA prompt — take the extra second to confirm.
- **"An app I approved is behaving strangely."** Go to **Settings → Connected Apps** and click **Revoke** next to it. Access stops within seconds.
- **"My AI client can't connect."** Make sure you're using `https://mcp.vetready.ai` (not `/mcp`). If you previously configured a hand-pasted token, remove it — the OAuth flow replaces it.
- **"My client claims a tool was rate-limited."** Normal at very high call rates; the error carries a `retry_after_s` hint. If you see it on quiet days, contact support — that shouldn't happen.

## Related

- [Connected Apps](/docs/connected-apps) — review and revoke AI clients that have access to your account.
- [Today's Schedule](/docs/todays-schedule) — what `get_schedule` returns when an AI asks about today.
- [Understanding Intake Summaries](/docs/understanding-intake-summaries) — the detail the AI reads for each completed intake.
- [Managing Your Team](/docs/managing-your-team) — roles affect what MCP tools can do on write calls.