MCP Server - NxVET API

Overview

The NxVET MCP server exposes the NxVET REST API as tools over the Model Context Protocol. Instead of writing integration code, point an MCP-capable AI assistant at https://mcp.nx.vet/mcp and it can list consultation records, read transcripts and SOAP notes, browse NxHub conversations and device timelines, and manage webhooks — all scoped to your organization by your API key.

Highlights

22 tools covering labels & transcripts, NxHub conversations, webhooks, and API keys
Your key, your data: every request is authorized with your own nxvet_sk_ key — the server stores nothing
Stateless: no sessions, no setup beyond one config entry

Quick Start

Generate an API key in the NxVET Integrations page → API Keys tab
Add the server to your MCP client (examples below)
Ask your assistant to call get_identity — it verifies the key and returns your organizationId, which the other tools need

Connecting Clients

# No code needed — OAuth flow in the browser:
# 1. claude.ai → Settings → Connectors → Add custom connector
# 2. URL: https://mcp.nx.vet/mcp
# 3. Click Connect — a NxVET page opens; paste your nxvet_sk_ API key
#    and approve. Done: Claude can now work with your clinic's data.
#
# Also works in the Claude Desktop & mobile apps via the same connector.
# Revoking the API key at app.nx.vet/integrations instantly disconnects it.

# OAuth flow in the browser (Plus/Pro/Business, Developer mode required):
# 1. ChatGPT → Settings → Apps → Advanced settings → enable Developer mode
# 2. Apps → Add more → create a custom app:
#      Name: NxVET
#      MCP server URL: https://mcp.nx.vet/mcp
#      Authentication: OAuth   (no client ID/secret — it self-registers)
# 3. Connect — a NxVET page opens; paste your nxvet_sk_ API key and approve.
# 4. In a chat, enable the NxVET app from the tools menu.
#
# Note: the NxVET app works in Developer-mode chats with all tools.
# ChatGPT's Deep Research / built-in search surfaces require special
# search/fetch tools, which this server does not expose yet.

claude mcp add nxvet --transport http https://mcp.nx.vet/mcp \
  --header "Authorization: Bearer nxvet_sk_YOUR_API_KEY"

{
  "mcpServers": {
    "nxvet": {
      "type": "http",
      "url": "https://mcp.nx.vet/mcp",
      "headers": { "Authorization": "Bearer nxvet_sk_YOUR_API_KEY" }
    }
  }
}

// claude_desktop_config.json — runs the npm package locally (requires Node 20+)
{
  "mcpServers": {
    "nxvet": {
      "command": "npx",
      "args": ["-y", "nxvet-mcp"],
      "env": { "NXVET_API_KEY": "nxvet_sk_YOUR_API_KEY" }
    }
  }
}

# ~/.codex/config.toml — runs the npm package locally (requires Node 20+)
[mcp_servers.nxvet]
command = "npx"
args = ["-y", "nxvet-mcp"]
env = { "NXVET_API_KEY" = "nxvet_sk_YOUR_API_KEY" }

npx @modelcontextprotocol/inspector
# Transport: Streamable HTTP
# URL: https://mcp.nx.vet/mcp
# Header: Authorization: Bearer nxvet_sk_YOUR_API_KEY

Which method? claude.ai / Claude Desktop / mobile / ChatGPT — use the OAuth connector (first tabs): paste your API key once in the browser, no config files. Developer tools (Claude Code, Cursor) — send the key as an Authorization header. Stdio-only clients (OpenAI Codex CLI) — run the npx nxvet-mcp npm package locally with the key in an environment variable. In every case, access is scoped to the API key's organization and revoking the key at app.nx.vet/integrations disconnects it instantly.

Available Tools

Area	Tools
Identity	`get_identity`
Labels & transcripts	`list_labels`, `get_label`, `assign_patient_to_label`, `aggregate_labels`, `regenerate_label`, `list_medical_templates`
NxHub conversations	`list_conversations`, `get_conversation`, `get_device_timeline`, `preview_conversation`, `create_conversation`, `complete_conversation`
Webhooks	`list_webhooks`, `create_webhook`, `delete_webhook`, `test_webhook`, `enable_webhook`, `get_webhook_deliveries`
API keys	`list_api_keys`, `create_api_key`, `revoke_api_key`

The tools mirror the REST endpoints one-to-one — the API Reference documents parameters, response shapes, and constraints (time-range limits, pagination styles, etc.).

Example Questions

Once connected, just ask in plain language — the assistant chains the tools for you. Answers are scoped to your organization by your API key, and dates work naturally (“today”, “this week”, “July 3rd”).

🩺 Veterinarian

“Show me my consultations from today.”
“Pull up the SOAP note for Buddy’s visit this morning.”
“Summarize the last three visits for the patient named Max.”
“Assign this recording to patient Bella — it’s on Default Patient.”
“Regenerate this note using the annual-wellness template.”

🏥 Clinic Owner / Manager

“How many consultations did the clinic record this week?”
“Break down this month’s recordings by type.”
“Which of our devices captured the most recordings today?”
“What webhooks do we have, and are any of them failing?”
“List our API keys and when they were last used.”

🧑‍💼 Front Desk / Staff

“Is the exam room 2 device recording right now?”
“There’s an active conversation on reception — complete it.”
“Find the recording for patient Charlie from last Tuesday.”
“Create a record from the lobby device between 10:00 and 10:30.”
“Show the transcript for the visit the vet just finished.”

🔌 Developer

“Walk me through the conversation lifecycle from active to uploaded.”
“Fetch a completed conversation and show its full JSON.”
“Set up a webhook to notify our PIMS when a conversation completes.”
“Create an API key for our reporting integration that expires at year-end.”

These are a starting point — anything the tools can do, you can ask for in your own words. Start broad (“list today’s recordings”), then drill in (“open the third one and read its SOAP note”); transcripts and notes come back when you open a specific record, not in list views.

Security

All traffic is HTTPS end to end; the server forwards your key only to https://app.nx.vet
The MCP server is stateless and holds no credentials, database, or cached data of its own
Authorization and organization scoping are enforced by the NxVET API exactly as for direct REST access — the MCP server grants no additional permissions
Revoking the API key (Integrations page or revoke_api_key) instantly cuts off MCP access
Treat the key like a password: prefer per-integration keys with expiry dates so MCP access can be rotated independently

Troubleshooting

401 on every call: the Authorization header is missing or the key is invalid/revoked. Test the key directly: curl -H "Authorization: Bearer nxvet_sk_..." https://app.nx.vet/api/auth/me
403: the key is valid but scoped to a different organization than the one you passed
Tool asks for an organizationId: call get_identity first — most tools require it
429: rate limited — back off and retry