> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ontime.hosai.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Claude

> Add OnTime as a custom connector in claude.ai or Claude Desktop, using the OAuth flow.

claude.ai and Claude Desktop connect to OnTime through OAuth. You will not paste an API key — you authorize the connector the way you would authorize any app.

## Add the connector

<Steps>
  <Step title="Open connector settings">
    In claude.ai or Claude Desktop, go to **Settings → Connectors → Add custom connector**.
  </Step>

  <Step title="Enter the MCP URL">
    ```text theme={null}
    https://app.ontime.hosai.app/api/mcp
    ```

    That is the only value you need. Everything else is discovered automatically.
  </Step>

  <Step title="Authorize">
    Claude sends you to OnTime's sign-in page. Sign in with your normal OnTime credentials, then review the consent screen: which organization, which employee, and what level of access.
  </Step>

  <Step title="Approve">
    Claude receives an access token bound to **you**, in that organization.
  </Step>

  <Step title="Test it">
    Ask Claude:

    > Use OnTime to tell me who I am.

    It should call `ontime_whoami` and come back with your name, your organization and your permissions. If it does, you are connected.
  </Step>
</Steps>

## What happens behind the scenes

You do not have to configure any of this — it is listed so you know what the connector is doing.

```mermaid theme={null}
sequenceDiagram
  participant C as Claude
  participant O as OnTime
  C->>O: POST /api/mcp (no token)
  O-->>C: 401 + WWW-Authenticate → discovery URL
  C->>O: GET /.well-known/oauth-protected-resource
  C->>O: GET /.well-known/oauth-authorization-server
  C->>O: POST /api/oauth/register (dynamic client registration)
  C->>O: GET /api/oauth/authorize (PKCE challenge)
  Note over O: You sign in and approve
  O-->>C: authorization code
  C->>O: POST /api/oauth/token (PKCE verifier)
  O-->>C: access + refresh token
  C->>O: POST /api/mcp (Bearer oat_…)
```

<Note>
  PKCE and dynamic client registration happen automatically. The initial `401` is not an error — it is how the connector discovers that OnTime speaks OAuth, via the `WWW-Authenticate` header.
</Note>

## Access levels

OnTime offers two OAuth scopes:

| Scope              | Grants                                                                                                               |
| ------------------ | -------------------------------------------------------------------------------------------------------------------- |
| `ontime:read`      | Read-only tools. Every read permission, plus a narrow set of action-shaped keys that gate genuinely read-only tools. |
| `ontime:readwrite` | The full catalog — **intersected with your own role**.                                                               |

<Warning>
  **`ontime:readwrite` does not grant more than you have.** The scope is intersected with your employee role's permissions, so authorizing it gives Claude exactly what you can already do in the app, and nothing more.

  If you are an ordinary employee, `ontime:readwrite` still cannot approve anyone's leave.
</Warning>

## Interactive views

Four tools can return a rich interactive view rather than raw text — team today, approvals, roster week and payslip.

<Note>
  **On claude.ai these currently degrade to text.** That is the designed fallback while support for interactive MCP views is still settling upstream, not a misconfiguration. Everything works; it just renders as text.
</Note>

## Revoking access

<CardGroup cols={2}>
  <Card title="From Claude" icon="unplug">
    Remove the connector in Settings → Connectors.
  </Card>

  <Card title="From OnTime" icon="shield">
    Revoke the session or the token in the admin console. Takes effect immediately.
  </Card>
</CardGroup>

Refresh tokens rotate on use, and reusing an old one revokes the whole family — so a stolen token stops working as soon as the legitimate client refreshes.

## If it will not connect

<AccordionGroup>
  <Accordion title="Claude reports it cannot reach the server">
    Confirm the URL is exactly `https://app.ontime.hosai.app/api/mcp` — including `/api/mcp` and with no trailing slash.
  </Accordion>

  <Accordion title="You get a 401 and no sign-in prompt">
    The connector could not discover the authorization server. Check that `https://app.ontime.hosai.app/.well-known/oauth-protected-resource` returns JSON in a browser.
  </Accordion>

  <Accordion title="Claude connects but sees almost no tools">
    That is your permissions, working as intended. Ask Claude to run `ontime_whoami` and compare against the [tool catalog](/ai-mcp/tool-catalog).
  </Accordion>
</AccordionGroup>

More in [Troubleshooting](/ai-mcp/troubleshooting).