Vet ReadyVet Ready
All documentation

MCP Integration (AI Clients)

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

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.

ToolPoolWhat it does
prepare_clinic_dayclinicSchedule + recently flagged intakes + team roster, in one call. Backs the "morning huddle" skill.
review_intake_and_respondclinicBehaviour profile + plan + transcript + prep progress for a single session, in one call.
onboard_clinicclinicDestructive — creates org + default clinic + invitations + flow-template catalog. Requires explicit confirmation.
find_clientclinicFuzzy-search across owner email/name + dog name within this org.
enrol_dog_for_visitconsumerCreate/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 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

Markdown version of this page: /docs/mcp-integration/index.md