> ## Documentation Index
> Fetch the complete documentation index at: https://build.practicehub.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Connectors

> Connecting Claude, ChatGPT and other AI apps with OAuth

AI apps that support remote MCP servers with OAuth connect to PracticeHub without any pre-registration: paste the clinic's MCP URL, approve access as yourself, done. Actions the assistant takes are then recorded against **you**, and revoking access is one click.

## Who can connect

Connecting is **opt-in per role**. Account owners can always connect an AI app; other team members can only if an account owner has enabled **Connect AI apps (Claude, ChatGPT)** for their role under **Settings → Security → Roles**. Anyone else reaching the consent screen is told exactly that. If the permission is later removed from a role — or the team member is deactivated — every connector they approved stops working immediately.

## What a connected team member can do

A connector acts **as that team member, with their PracticeHub role** — the AI app can do no more than the person could in PracticeHub:

* **Reads** follow the role: appointments and availability need calendar access; invoices, payments and allocations need *View all patient financial data*; everything else is visible to any connected team member.
* **Writes** follow the role: patients, files and patient logs need *Edit patient*; appointments need calendar access (a *read-only calendar* role cannot book, move or cancel); invoices and payments need *Edit patient financials* (the same-day-only variant does not count); allocations need *Allocate payments*; deleting an appointment, patient or document needs the matching *delete* permission; reference data (appointment types, locations, referral sources, …) needs *Access settings*.
* **Ringfencing applies**: a role limited to *own patients* sees and writes only the patients they are the default practitioner for (and cannot create patients through a connector — a new patient would have no default practitioner); a role limited to *own calendar* sees only their own diary and can only book or move appointments within it.
* Account owners hold every permission.

A refused call comes back as `403 permission_denied` naming the missing permission. API keys are different: they are not people, so they carry `read` / `write` abilities instead — see [Authentication](/authentication).

## Connect Claude

<Steps>
  <Step title="Add a custom connector">
    In Claude (web or desktop) open **Settings → Connectors → Add custom connector** and enter the clinic's MCP URL:

    ```
    https://your-clinic.your-region.practicehub.io/v3/api/mcp
    ```

    No client id or secret is needed — Claude registers itself with the server.
  </Step>

  <Step title="Approve access">
    Claude opens a PracticeHub page on the clinic domain. Log in if you are not already, then review and approve the request. You are approving on your own account: the assistant gets what you can see and do, nothing more.
  </Step>

  <Step title="Use it">
    Enable the connector in a conversation and ask, for example, *"Which of Dr Rae's patients have appointments tomorrow?"* or *"Book Ada Lovelace a new patient consultation with Sam next Tuesday morning."* Claude will look things up first and ask before booking.
  </Step>
</Steps>

Other MCP-capable apps (ChatGPT, Cursor, and agent frameworks that implement the OAuth flow) work the same way with the same URL.

## What happens under the hood

The server implements the MCP authorization specification:

| Step                           | Endpoint                                      |
| ------------------------------ | --------------------------------------------- |
| Discovery                      | `GET /.well-known/oauth-authorization-server` |
| Dynamic client registration    | `POST /v3/oauth2/register`                    |
| Authorization (consent screen) | `GET /v3/oauth2/authorize` — PKCE required    |
| Token exchange and refresh     | `POST /v3/oauth2/token`                       |

Only known AI apps can register: redirect URLs must be on an allow-listed host (Claude, ChatGPT, …) — and the consent screen shows where you'll be sent back to, so check it matches the app you're connecting. Tokens are issued for the scope `mcp:use`, are tied to the team member who approved and to that clinic's account, and are short-lived (access tokens last an hour; the client refreshes them automatically, and refresh tokens rotate on use and lapse after 30 days idle). A connector cannot reach another clinic's data even if the same person has access to several — connect each clinic's URL separately.

## Revoking

Signing out of PracticeHub does not disconnect a connector. To cut one off from the PracticeHub side — a lost device, a departed team member — an administrator opens **Developers → API Keys → Connected AI apps** and revokes it; the assistant loses access immediately (its refresh token is revoked too, so it cannot silently reconnect). Removing the connector in the AI app's own settings also stops it. Deactivating a team member's PracticeHub account disconnects every connector they approved.

## Headless agents

If you are building your own agent (no human in the loop), skip OAuth and use an API key as a Bearer token — see [MCP Server](/mcp/overview#authentication). Actions are recorded against the integration rather than a person.