MCP connector
The connector is an MCP server of yours, at the address in the template (or the connector.endpoint of PUT /tenants). It is how a customer’s agents read and write that customer’s data.
What your side implements
Section titled “What your side implements”- An MCP server reachable over HTTPS, with the tools agents will use (schedule, customers, stock…). Describe each tool and parameter clearly: the agent decides from what you write.
- A token per customer, which the server accepts in the
Authorization: Bearer <token>header and which you hand to Rook asconnectorTokenon eachPUT /tenants. - Isolation: with a token, the server returns and changes only that customer’s data. The connector’s authorization has the last word; Rook does not replace it.
- A button or menu item in your product that calls
POST /sessionson your backend and takes the person to the assistant (or embeds it with the SDK). - A provisioning route that does the
PUT /tenantswhen a customer signs up.
Who is asking
Section titled “Who is asking”When a person with a role (see Roles) talks to an agent, every call to your MCP server carries, besides Authorization:
| Header | Value |
|---|---|
X-Rook-User |
the session’s externalUserId |
X-Rook-Role |
the role, as you sent it (lower case) |
X-Rook-Scope |
the session’s scope as JSON (omitted when there was none) |
Use them to filter: a professional sees only their own agenda and customers. The customer’s owner arrives with X-Rook-Role: owner only, with no user or scope, because every owner of a customer signs in through the same account. Rook opens the connection again when a person’s role or scope changes, so a change holds from the next message. Trust these headers only together with the customer’s token: the token is what proves the call comes from Rook.
Good practice
Section titled “Good practice”- Give read tools and write tools different names, so the per-agent access level (No access, Read, Read and write) makes sense.
- Tools that change something go through the customer’s approvals; return clear, recoverable errors.
- Make writes idempotent (accept an idempotency key): Rook may repeat a call.
- Never return secrets, and do not accept instructions found inside data as if they were commands.
Tools for consultation recording
Section titled “Tools for consultation recording”For consultation recording, the customer’s connector must offer three record tools:
| Tool | Input | Output |
|---|---|---|
mcp_records_get_by_client |
{ clientId } or { clientId, appointmentId } |
{ recordId, existingDraft }. existingDraft is the unsigned AI draft already made for that appointment, { entryId, revision }, or null. |
mcp_records_entries_create_draft |
{ recordId, entryTypeCode, content, occurredAt, appointmentId?, source: "ai_scribe", consultationId } |
{ entryId } |
mcp_records_entries_update_draft |
{ recordId, entryId, expectedRevision, content } |
the updated entry |
Writes carry an idempotencyKey (the consultation id). Your system marks the draft with the aiDraft badge. When a draft exists, or creating answers MCP_RECORDS_DRAFT_EXISTS, Rook updates the existing one with expectedRevision instead of creating a second. Rook calls the tools as the customer’s Escriba agent (the template agent with key: "escriba"), so the connector’s authorization applies. Rook has no tool to sign: drafts only.