> ## 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 Code

> Wire OnTime into Claude Code with an API key, and install the plugin that bundles three operational skills.

Claude Code can set headers, so it uses an **API key** directly — no OAuth flow needed.

## Option 1 — add the server directly

<Steps>
  <Step title="Issue an employee-bound API key">
    In the admin console: **API & webhooks → Issue key**. Bind it to the employee you want the agent to act as.

    <Warning>
      **Bind it to an employee.** An unbound *service* key cannot call any self-service or scope-checked tool — no punching, no approvals, no "my" anything.
    </Warning>

    The key is shown once. Copy it.
  </Step>

  <Step title="Add the server">
    ```bash theme={null}
    claude mcp add ontime --transport http \
      https://app.ontime.hosai.app/api/mcp \
      --header "Authorization: Bearer ont_..."
    ```
  </Step>

  <Step title="Verify">
    ```text theme={null}
    > Use OnTime to tell me who I am.
    ```

    Claude calls `ontime_whoami` and reports your identity, organization and permissions.
  </Step>
</Steps>

## Option 2 — install the plugin

The plugin wires the same server **and** ships three skills that teach Claude how to operate OnTime properly.

<Steps>
  <Step title="Add the marketplace">
    ```text theme={null}
    /plugin marketplace add <path-to-the-ontime-repo>
    ```
  </Step>

  <Step title="Install">
    ```text theme={null}
    /plugin install ontime@ontime
    ```
  </Step>

  <Step title="Set the environment variables">
    ```bash theme={null}
    export ONTIME_MCP_URL="https://app.ontime.hosai.app/api/mcp"
    export ONTIME_API_KEY="ont_..."
    ```

    `ONTIME_MCP_URL` defaults to `http://localhost:3000/api/mcp` for local development, so set it explicitly when pointing at a real instance.
  </Step>
</Steps>

## The three bundled skills

Skills load automatically when the conversation matches what they cover.

<AccordionGroup>
  <Accordion title="ontime-operations — the always-relevant reference" icon="book">
    Loads for essentially any OnTime work. Covers:

    * Grounding with `ontime_whoami` before anything else.
    * **The self-service versus on-behalf split** — most domains are two separate tools, not one with an optional `employeeId`. This is the single biggest source of agent errors, and this skill exists largely to prevent it.
    * Which tool for which job, id and date conventions, pagination, error recovery.
    * The four confirm-gated tools, and the requirement to get an explicit human "yes" first.
    * A full annotated catalog of all 71 tools.
  </Accordion>

  <Accordion title="ontime-attendance-workflows" icon="clock">
    Loads for attendance work: missed punches, regularization queues, overtime approvals, day corrections — end to end rather than tool by tool.
  </Accordion>

  <Accordion title="ontime-payroll-runbook" icon="indian-rupee">
    Loads for payroll and compliance: the five-stage cycle, what to verify between stages, and disbursement sign-off.

    Payroll is a state machine where calling a stage out of order fails, so this one is worth having loaded before you start rather than after the first refusal.
  </Accordion>
</AccordionGroup>

## Which employee should the key be bound to?

The agent inherits that person's authority exactly. Choose deliberately:

| Bind to                  | The agent can                                                                               |
| ------------------------ | ------------------------------------------------------------------------------------------- |
| **An ordinary employee** | Punch, apply for leave, request corrections, read their own pay. Nothing about anyone else. |
| **A manager**            | All of the above, plus see and decide their direct reports' requests.                       |
| **An HR or Admin user**  | Organization-wide reach, including payroll and compliance.                                  |

<Warning>
  Binding to an Admin gives the agent the run of the organization — including disbursing payroll. The confirm gates help, but the right first step is to bind narrowly and widen when you need to.
</Warning>

## Rotating the key

There is no rotate action. Issue a new key, update `ONTIME_API_KEY` (or re-add the server), then revoke the old one.

## If a tool is missing

Not a bug — a permission. Run `ontime_whoami` and compare against the [tool catalog](/ai-mcp/tool-catalog). Listing and calling share the same check, so a tool you cannot see is one you could not call anyway.