Vetwise

A self-hosted MCP server that owns a household's pet records and answers "is this safe for my pet?" with species- and weight-aware toxicosis math and cited veterinary sources.

Vetwise is built for the ten minutes after a pet eats something wrong: a dog into a chocolate bar, a cat near a lily, a sitter who is not sure whether the evening dose was given. It is not a chatbot with a toxicology page pasted into its prompt. The server owns the household record, runs a deterministic safety engine, and returns one of five verdicts — including unverified when a fact is missing. A host (Claude, Alexa+, a local UI) talks to it over Streamable HTTP with a scoped bearer token.

Not veterinary advice. Vetwise names the veterinarian and poison-control numbers; it never advises treatment or inducing vomiting.

Run the demo

npm install
cp .env.example .env        # optional; every value has a working demo default
npm start                   # http://127.0.0.1:3000

Open http://127.0.0.1:3000. The demo clock is frozen at 21:40; the household has two pets and two doses still due. The page is a simulator: every answer it shows came from a real JSON-RPC tools/call against /mcp, and the traffic panel lists those calls.

Suggested first line: “What's due tonight?”

The full scripted walkthrough is in docs/DEMO.md.

Demo household

Related MCP server: veterinary-fda

What is inside

9 MCP tools

6 resources

vetwise://household, vetwise://pets/{petId}, vetwise://care/today, vetwise://medications, vetwise://toxins, vetwise://toxins/{toxinId}.

2 prompts

evening_check_in and something_my_pet_ate — the two shapes a real host would ship as suggested actions.

24 catalogued toxins

Foods, plants, human medicines, pesticides and household products. Every entry carries a published source URL and a verbatim quote. The full table with thresholds is in docs/TOXIN_CATALOGUE.md.

Verdicts

emergency · call_vet · monitor · no_known_toxicity · unverified

unverified is a first-class answer. Missing weight, amount, species, product or a substance outside the catalogue never becomes reassurance. Grapes/raisins, lilies, rodenticide and antifreeze escalate on any exposure, before any amount is requested.

How a request flows

browser / host
   │  Bearer token
   ▼
Express  ──►  /mcp  ──►  MCP server (tools · resources · prompts)
   │                         │
   │                         ├─ scope check inside every tool
   │                         ├─ deterministic safety engine
   │                         └─ JSON-file store (atomic writes)
   │
   ├─ /api/chat  ──►  scripted planner or Bedrock planner
   │                    └─ its own short-lived MCP client ──► /mcp
   ├─ /api/state ──►  household snapshot + MCP traffic log
   └─ /            ──►  static simulator

The planner has no private access to the store. It is just another MCP client, authenticated with the same token the browser sent, so the traffic panel shows exactly what the model saw and called.

Deeper design notes: docs/ARCHITECTURE.md. Safety policy: docs/SAFETY.md.

Agent modes

• scripted (default with no AWS credentials) — a deterministic planner that recognises exposure, symptom follow-up, medication logging, alerts and two-phase record changes. No network model call.

• bedrock — Amazon Bedrock Converse tool loop (VETWISE_AGENT=bedrock, AWS credentials required). If Bedrock fails, the turn falls back to the scripted planner and labels the answer.

Both paths call the same MCP tools over the same transport. The UI badge says which planner answered.

Configuration

Copy .env.example to .env. The values that matter:

Run with an env file if you prefer:

node --env-file=.env --import tsx src/index.ts

Deploy a public demo

A hosted demo lets a buyer try every tool, writes included, from a link. Strangers will change the record, so a public demo turns on the reset: the household, chat transcripts and traffic panel are reseeded every VETWISE_DEMO_RESET_MINUTES, and the simulator shows a "Public demo · resets in N min" notice. Requests still running when a reset fires cannot write into the fresh household, and if a reset cannot be saved, /healthz answers 503 and the demo refuses requests until the next attempt succeeds.

Render (one click). render.yaml describes a free Docker web service with the demo clock at 21:40 and a 30-minute reset. In Render choose New → Blueprint, pick this repository, and deploy.

Any container host.

docker build -t vetwise .
docker run -p 3000:3000 -e DEMO_CLOCK=21:40 -e VETWISE_DEMO_RESET_MINUTES=30 vetwise

The image binds 0.0.0.0, runs the scripted planner, keeps its data in /app/data (mount a volume to keep a real household), and has a /healthz health check. Render and similar hosts set PORT; the server's self-call follows it.

A public demo runs on the published demo tokens. For a real household, set NODE_ENV=production, OWNER_TOKEN and SITTER_TOKEN, and leave DEMO_CLOCK and VETWISE_DEMO_RESET_MINUTES unset; the server refuses to start otherwise.

Connect from an MCP client

The server speaks Streamable HTTP at /mcp with a bearer token. Replace the URL with your deployment and the token with the owner or sitter token.

Claude Code

claude mcp add --transport http vetwise https://your-host/mcp \
  --header "Authorization: Bearer maya-owner-demo-token"

Claude Desktop (through the mcp-remote bridge, in claude_desktop_config.json)

{
  "mcpServers": {
    "vetwise": {
      "command": "npx",
      "args": ["mcp-remote", "https://your-host/mcp", "--header", "Authorization:${VETWISE_AUTH}"],
      "env": { "VETWISE_AUTH": "Bearer maya-owner-demo-token" }
    }
  }
}

MCP Inspector: npx @modelcontextprotocol/inspector, transport Streamable HTTP, URL https://your-host/mcp, header Authorization: Bearer ….

Then ask the host "Mochi ate half a bar of dark chocolate" and watch the same tools the simulator uses.

Scripts

npm run typecheck   # tsc --noEmit
npm test            # safety-engine unit tests (17)
npm run smoke       # boots the real server and drives it with a real MCP client
npm run regress     # replays every finding in Vetwise-Code-Review.md
npm run check       # all four
npm run dev         # tsx watch

The smoke test starts its own server on port 8799 with a temporary data file, exercises all 9 tools, both identities, resources, prompts, single-use confirmations and the 401 gate, then removes its data. npm run regress boots a second server on 8811 and asserts the review fixes over real HTTP and MCP: hashed tokens, caller-bound sessions, /healthz minimalism, security headers, rate limiting, sanitised alert bodies, medication routes, id length, and the startup refusals.

Security posture

• Bearer tokens are stored as SHA-256 digests and compared with timingSafeEqual; the raw secret never leaves the request that carried it, and /api/whoami only ever returns a four-character hint.

• Published demo tokens work only in demo mode. NODE_ENV=production (or VETWISE_DEMO=0) refuses to start without OWNER_TOKEN and SITTER_TOKEN, and rejects the demo strings outright.

• Chat sessions are keyed by clientId:sessionId, expire after 30 minutes, and are capped at 200.

• /api/chat is rate limited per token (20/min), request bodies over 2,000 characters are refused, and the client sees one generic error while the operator sees the full cause.

• The static app is served with a strict CSP (default-src 'self'), nosniff, X-Frame-Options: DENY and no third-party origins.

• /healthz returns { ok, time } only; version, agent mode and model are not public.

• Alert bodies are stripped of control characters and angle brackets before they reach the outbox or a webhook.

• npm run regress proves each of those still holds.

Safety posture

• The engine never invents a threshold. Every band traces to a cited source, and every answer carries the evidence it used.

• Missing facts produce unverified with a concrete next step (get a weight, read the package, call poison control).

• Symptoms can only raise a verdict, never lower it.

• Dose bands can raise a gate verdict but never lower one.

• Record changes are two-phase and bound to the caller; replay is rejected.

• Alerts go only to people on the household record.

• No treatment advice, no induced vomiting, no therapeutic dosing. Ever.

no_known_toxicity exists as a verdict but is currently unreachable for the 24 catalogued toxins: every published band starts at 0 and resolves to monitor or higher. It is documented as reserved rather than used to manufacture false reassurance. See docs/SAFETY.md.

Licence

MIT — see LICENSE.