MCP

MCP server

Connect AI agents to your clinic over the Model Context Protocol — the same patients & appointments API, exposed as MCP tools.

The MCP server exposes the ManaNotes External API to AI agents and MCP-compatible clients over the Model Context Protocol, using the Streamable HTTP transport. It’s a second front door onto the same API as the REST endpoints — same data, same rules — surfaced as callable tools rather than routes.

Endpoint

A single Streamable HTTP endpoint. Send MCP JSON-RPC requests with POST; the server is stateless (no session or SSE stream), so GET and DELETE aren’t used.

MCP endpoint

POST https://api.mananotes.co.nz/mcp

Authentication

Two ways in, same rules once connected:

1. Sign in with ManaNotes (OAuth). The server implements the MCP authorization spec — OAuth 2.0 discovery, dynamic client registration and the authorization-code + PKCE flow. OAuth-capable MCP clients (claude.ai custom connectors, and any client that walks the WWW-Authenticate challenge) need no pasted credentials at all: the client registers itself, a ManaNotes practitioner signs in and approves the connection on a consent page, and tokens refresh automatically from then on. The connection acts as the approving practitioner and sees only that clinic’s data.

2. Static bearer token. For headless/server-side clients: the same OAuth 2.0 client-credentials (M2M) access token as the REST API, sent as an Authorization header. The same client_id / client_secret work for both — head to Authentication to get a token.

Connect from claude.ai

Add ManaNotes as a custom connector: in claude.ai go to Settings → Connectors → Add custom connector and paste the endpoint URL:

Custom connector URL

https://api.mananotes.co.nz/mcp

Claude opens a ManaNotes window: sign in with your usual practitioner account, review the access being requested, and click Approve connection. That’s it — no client id, secret or token to copy. The connection appears in ManaNotes under Settings → Integrations → API access with a Connected app badge; hit Disconnect there at any time to cut the connector off immediately (approve again from the client to reconnect).

Connect with a static header

Clients that support custom headers (Claude Code, Cursor, the MCP SDKs) can skip the interactive flow and present a client-credentials token directly:

MCP client config

{
  "mcpServers": {
    "mananotes": {
      "type": "streamable-http",
      "url": "https://api.mananotes.co.nz/mcp",
      "headers": {
        "Authorization": "Bearer eyJhbGci..."
      }
    }
  }
}

Access tokens are short-lived — refresh them with the client-credentials grant and update the header when they expire. (OAuth-connected clients handle refresh automatically; static headers are best for headless setups that already manage tokens.)

Tools

Tools mirror the REST endpoints one-to-one: each requires the same scope as its REST equivalent, validates the same inputs and runs the same operation against your clinic. A client only sees the tools its scopes allow.

Tool	Scope	What it does
`whoami`	—	Return the calling client: clinic, acts-as practitioner and granted scopes.
`list_patients`	`patients:read`	List / search patients (limit, offset, search, locationIds).
`get_patient`	`patients:read`	Fetch a patient by id.
`create_patient`	`patients:write`	Create a patient.
`update_patient`	`patients:write`	Update a patient.
`delete_patient`	`patients:write`	Archive (soft-delete) a patient.
`list_appointments`	`appointments:read`	List appointments in a date range (from, to, locationIds).
`get_appointment`	`appointments:read`	Fetch an appointment by id.
`create_appointment`	`appointments:write`	Book an appointment.
`update_appointment`	`appointments:write`	Update / reschedule an appointment.
`delete_appointment`	`appointments:write`	Cancel (soft-delete) an appointment.
`list_practitioners`	`appointments:read`	List practitioners (needed to book).
`list_billable_items`	`appointments:read`	List billable items / services (needed to book).
`list_locations`	`appointments:read`	List the clinic’s locations (sites).
`list_practitioner_working_hours`	`appointments:read`	List a practitioner’s weekly working hours & breaks.
`get_practitioner_availability`	`appointments:read`	Compute a practitioner’s open slots for a service across a date range.

Conventions

Tool results return the same JSON shapes as the REST responses, and errors come back as MCP tool errors carrying the same stable codes (e.g. a missing record is NOT_FOUND) — see Errors & conventions. IDs, dates and soft-delete behaviour are all identical to REST.