MCP setup

Use your own Hopshift account with management access. Browser authorization must be enabled; otherwise use the advanced personal-key setup.

Quick setup

App links open the installed client so you can review its setup. Client availability and organization policies may vary.

Connect with browser authorization

You need a client that supports Streamable HTTP and OAuth authorization-code sign-in. You do not need to deploy a server or set up Cloudflare to use the hosted service.

Data returned by Hopshift becomes available to your chosen AI client. Use a client your organization permits for employee and payroll data. Client names are supplied by the client and are not verified identities.

1. Add https://hopshift.app/api/v1/mcp to your client's remote MCP servers using the instructions below. Do not configure an API-key header for this flow.
2. Choose the client's sign-in or connect action. In the browser, verify you are on your Hopshift deployment, then sign in with your own account and complete any required additional verification.
3. Review the client name and callback destination. Select the group whose data the client may access. Each connection is restricted to that group.
4. Keep the default read-only access for your first connection. Only requested write capabilities appear; they start unchecked. Select a write capability only if you need it and understand the actions it permits.
5. Click Authorize, return to the client, then run the first request.

Authorization gives the client ongoing access within the approved scope. It does not approve each future action individually. Your Hopshift login session is not passed to the client; it receives separate MCP credentials.

Connection settings

Hopshift supports public clients with dynamic client registration. HTTPS and localhost callbacks must match the registered address exactly. HTTP loopback-IP callbacks (127.0.0.1 or [::1]) may use a different port; every other part must match. Code exchange must use the exact callback sent during authorization. No client secret is required. Client ID Metadata Documents and arbitrary metadata URL fetching are not supported. Clients must send the server URL as their OAuth resource.

Claude (web, desktop and mobile)

Add the connector once on claude.ai or in the Claude desktop app. It then appears in Claude's mobile apps on the same account.

1. Open Customize → Connectors → Add → Custom → Web.
2. Name the connector Hopshift and paste https://hopshift.app/api/v1/mcp.
3. Under Authentication, choose Sign in now. Under OAuth client, choose Register automatically. Leave Request headers empty and Advanced unchanged, then add the connector.
4. Select Connect. On the Hopshift page, check that Authorization will return to shows https://claude.ai/api/mcp/auth_callback, choose your group, then select Authorize.
5. In a new chat, turn on Hopshift from the tools menu and run the first request.

The Hopshift page lists every write capability, all unchecked. Select only the ones you need; tools for unselected capabilities do not appear in Claude. Under the connector's Tool permissions, keep Needs approval for write tools so Claude asks before it changes anything. To change permissions later, revoke the connection on MCP connections, then disconnect and connect again in Claude.

On Team and Enterprise plans, an organization Owner may need to add the connector or allow custom connectors before members can connect. Each person still connects with their own Hopshift account. See Claude's connector guide.

Claude Code

claude mcp add --transport http --scope user hopshift https://hopshift.app/api/v1/mcp

Start claude, open /mcp, select Hopshift and authenticate. Complete the Hopshift consent screen. See the official Claude Code instructions.

Cursor

Merge this into your personal ~/.cursor/mcp.json, preserving existing servers:

{
  "mcpServers": {
    "hopshift": {
      "url": "https://hopshift.app/api/v1/mcp"
    }
  }
}

Open Customize → MCPs, enable Hopshift and follow its sign-in prompt. See the official Cursor authentication guide.

Codex CLI

codex mcp add hopshift --url https://hopshift.app/api/v1/mcp
codex mcp login hopshift --scopes mcp:management

If adding the server already completed browser sign-in, the second command is unnecessary. For an existing personal-key entry, remove its bearer_token_env_var or Authorization header before using OAuth. See the official OpenAI MCP guide.

To request an optional capability, reconnect with that scope, for example codex mcp login hopshift --scopes mcp:management,mcp:shifts:write, and explicitly select it on Hopshift's consent screen. A client cannot silently add permissions to an existing connection.

Other clients

Use a remote HTTP OAuth connection with public-client dynamic registration, S256 PKCE and a resource indicator. Client support varies by version; the examples above are configuration instructions, not a claim that every client version has been tested. Opening the MCP endpoint in a browser is not a connection test.

Use a native client or a connector that sends MCP requests from its server. Browser-only clients sending another website's Origin cannot call the MCP endpoint directly; OAuth endpoint CORS does not change that restriction.

Complete the first authorization within one hour of client registration. If an abandoned setup reports an unknown client, remove and re-add the server in your client to register again. This deadline does not expire an already authorized connection.

Manage or revoke an authorized connection

Open your group's MCP connections page and find Authorized AI clients. Review the client, permissions and expiry; use Load more to find older connections. Owners can select Show all authorized clients in this group (owner only) to inspect and revoke group connections. Revoke the connection to reject subsequent access and refresh requests immediately. Revocation does not undo completed changes, cancel work already in progress or erase information already returned to the client.

Connections expire after at most 30 days. Access tokens last at most 10 minutes; refresh tokens rotate when used and cannot extend the connection's original expiry. Reusing a consumed refresh token revokes the entire connection. If this happens, reconnect through the browser rather than repeatedly retrying it.

Each connection allows 24 refreshes per one-hour window. A 429 response includes Retry-After in seconds and leaves the current refresh token usable; wait before retrying.

Signing out of Hopshift, changing your login email or removing a client's local configuration does not revoke its Hopshift connection. Revoke it on MCP connections when access should end. Removing group membership or reassigning that membership to another account or group permanently invalidates its connections; adding the original membership back does not restore them. To change the selected group or permissions, revoke and authorize a new connection.

Verify your first connection

Start a new conversation in your configured client and ask:

Use Hopshift to list the companies I can access. Do not change anything.

The client should call list_workspaces and show only companies your account can access in the connection's selected group. Successful tool output verifies the connection; a saved configuration alone does not. If it fails, use Troubleshooting.

Choose one returned company, then try:

Show next week's shifts for [company name], with the exact date range you used. Do not change anything.

Or:

List pending leave requests I can review for the next 30 days, with the exact date range used. Include the company for each request and do not approve or reject anything.

Approval queues may include multiple companies within your permitted approval scope. Ask the client to follow pagination when you need the full list. You do not need a write-enabled connection for these examples.

Permissions and available actions

All OAuth connections and personal keys include read-only mcp:management. Optional capabilities add the following actions, subject to your existing Hopshift permissions:

Tool discovery omits writes the connection does not allow. A capability does not elevate your account: company access, outlets, reporting lines, approval rules and field permissions are checked again for every operation. OAuth connections and personal keys inherit your permitted companies and outlets throughout the selected group; you cannot narrow them to selected companies, outlets or read categories. Read-only access can therefore include sensitive payroll data you are already allowed to see.

Write-enabled calls can change live data. Hopshift does not add a separate human confirmation step for permitted MCP writes. Configure your client's approval controls and review the target company, people, dates and action before allowing a write. A prompt asking for confirmation is guidance to the client, not a server-enforced safeguard.

Payroll publication, payslip release and forced attendance-related shift changes remain in the Hopshift app. MCP also has no account-access, access-level, API-key or login-email management tools. For exact tool names, see Management tools.

Changes to your account access change what the connection can do. Loss of management permission prevents management operations. Non-owners with employment history in the group also need an ACTIVE or ON_LEAVE employment; owners and managers without employment history are not subject to that employment check. Outlet publication affects the outlet's schedule, including people outside your reporting line where the app's schedule-management policy permits it; whole-company publication requires company scope.

OAuth does not prevent prompt injection. Treat employee notes and other returned text as untrusted data, and review write requests in your client. Server permission checks still apply if an assistant follows malicious instructions.

Advanced personal-key setup

Create your personal connection

1. Sign in to Hopshift with your own admin or manager account, including supervisors with management access.
2. Select your group and open MCP connections in the sidebar (/{groupSlug}/mcp). Expand Advanced: personal API keys.
3. Click Create API Key and give it a recognizable name, such as Claude Code — my laptop. Choose an expiry date; the default is 30 days and the maximum is 90 days, counting today. For your first connection, leave all write capabilities unchecked.
4. Click Create Key, then Copy when the key is shown. The full key is displayed only once. Keep it in your private credential store; do not paste it into a chat, screenshot, URL or shared repository.

Create a separate key for each person and client. Never share an admin's key with a manager. Use MCP connections for this guide; Group Settings → API Keys creates a different kind of employee integration key.

Connection settings

Configure the header on every request, using your client's private credentials or configuration. Keep the key out of URLs and shared repositories. This advanced setup uses a manually configured Bearer header. For browser authorization, use the OAuth instructions above.

Make the key available to your client

The examples below read HOPSHIFT_API_KEY from the client's environment. In Bash or Zsh on macOS/Linux, run the following, paste the key at the hidden prompt, and press Enter:

read -r -s HOPSHIFT_API_KEY
export HOPSHIFT_API_KEY

In PowerShell, use:

$env:HOPSHIFT_API_KEY = [System.Net.NetworkCredential]::new('', (Read-Host 'Hopshift API key' -AsSecureString)).Password

Launch your client from that same terminal. The variable lasts for that terminal session; set it again in a new terminal or use your own private environment/secret manager. An already running app does not inherit a new export, and putting the key in a project's .env file alone does not configure these connections. The variable must be available each time the client starts.

Claude Code — API key

With the environment variable set, add Hopshift to your personal configuration:

claude mcp add --transport http --scope user \
  --header 'Authorization: Bearer ${HOPSHIFT_API_KEY}' \
  hopshift https://hopshift.app/api/v1/mcp

Keep the single quotes so the configuration stores the variable reference. Start claude, use /mcp to inspect Hopshift, then try the first request. claude mcp list confirms registration; it does not by itself prove a tool call works. See the official Claude Code MCP documentation.

The command uses Bash/Zsh line continuations. In PowerShell, enter it on one line, keeping the single-quoted header.

Cursor — API key

Merge this entry into your personal ~/.cursor/mcp.json (%USERPROFILE%\.cursor\mcp.json on Windows). Keep any existing servers:

{
  "mcpServers": {
    "hopshift": {
      "url": "https://hopshift.app/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${env:HOPSHIFT_API_KEY}"
      }
    }
  }
}

Fully quit Cursor, then launch it from the terminal with the variable set (for example, cursor . if its shell command is installed). Open Customize → MCPs, enable Hopshift if needed, then try the first request. Connection details appear in Output → MCP Logs; do not share logs containing credentials.

Remote HTTP connections do not support envFile. See Cursor's configuration guide and setup help.

Codex CLI — API key

With the environment variable set, register the connection:

codex mcp add hopshift --url https://hopshift.app/api/v1/mcp --bearer-token-env-var HOPSHIFT_API_KEY

Alternatively, merge this into your personal ~/.codex/config.toml:

[mcp_servers.hopshift]
url = "https://hopshift.app/api/v1/mcp"
bearer_token_env_var = "HOPSHIFT_API_KEY"

Use codex mcp list to check registration, then start codex from that terminal and try the first request. For this personal-key configuration, do not run codex mcp login hopshift; switch to the OAuth instructions above for browser authorization. See the official OpenAI MCP documentation.

Other clients

Choose a remote Streamable HTTP server, enter the server URL above, and configure the Bearer header in the client's private credential settings. A browser visit to the endpoint is not a connection test. If the client cannot supply that header, use one of the clients above.

Rotate or revoke a key

Open MCP connections to revoke an unused, lost or exposed key. Subsequent requests are rejected; revocation does not undo completed changes or erase data already returned to a client. If you lost the full key, create a replacement; it cannot be displayed again.

To rotate a key or change its capabilities:

1. Create a replacement key with the required expiry and capabilities.
2. Replace the value of HOPSHIFT_API_KEY and restart your client.
3. Verify the read-only first request, then revoke the old key. If the old key is exposed, revoke it immediately before setting up the replacement.

Expiry dates include the entire selected UTC date. Group owners can select Show all personal keys in this group (owner only) to view creator IDs and revoke any personal key in the group. Key management is unavailable while viewing another account.

Troubleshooting

Clients can receive a tool error even with HTTP 200. Inspect the tool result, not just the HTTP status. Share only redacted error details with support; never send your key.

Management tools

Start with list_workspaces. Pass a returned company_id to every other management tool. Use internal IDs returned by tools; employee codes can repeat across companies. Tool discovery (tools/list) supplies the complete input schemas.

Approval queues span the group's permitted approval scope: their company_id selects your context, and results may include other companies you can review. Shift and payroll tools target the chosen company. Existing outlet, reporting, delegation, intercompany and self-approval restrictions still apply.

Schedule and approval date ranges are inclusive and limited to 93 days. Follow the returned pagination fields; an initial page is not the entire queue. Shift times use local workplace HH:mm; correction timestamps require an explicit UTC offset. Pass a clock record's updatedAt as expected_updated_at when reviewing it, and refresh stale records before retrying.

Clock and correction list ranges use UTC day boundaries.

Leave reviews also require expected_updated_at from the displayed queue record. Set request_kind to leave or cancellation to identify the decision you reviewed. A concurrent request change is rejected instead of turning leave approval into cancellation approval.

Correction reviews require the updatedAt from list_attendance_corrections as expected_updated_at and accept only pending requests. Refresh a changed request before reviewing it; completed corrections cannot be amended through MCP.

Leave balances, imports and approved requests

list_leave_types and list_leave_balances are read-only. Both accept limit (1–100, default 50) and cursor; keep following nextCursor while hasMore is true. Balances target company_id, optionally filter employee_id, and report the company-local asOfDate. Use their structured rows for client-side CSV exports and resolve imported employee codes to internal IDs first.

The two leave writers require mcp:leave:write and your existing Hopshift authority. Approval permission alone does not enable them. Existing connections keep their original permissions: authorize a new connection with this capability, or create a replacement personal key. Refreshing an old OAuth token cannot add it.

Each call supplies company_id, a unique idempotency_key (8–128 letters, digits, ., _, :, or -), rows (1–50), and optional dry_run. Every row belongs to the selected company and needs a reason. Preview with dry_run: true; no changes, receipts or employee notifications are committed. A successful preview does not reserve the records: permissions and values are checked again on apply.

For set_leave_balances, each row has employee_id, mode, days and reason. Use allocation_id from the balance read to change an existing period. To create a missing allocation, instead provide leave_type_id, period_start and period_end as explicit YYYY-MM-DD dates; overlapping periods are refused. mode: entitlement sets allocated entitlement while preserving committed usage. mode: available sets the amount available on the current company-local date after usage, pending holds and expiry. Amounts use half-day increments; an available-balance correction may change at most 365 days per row. Exact results include entitlement, available, pending, used and asOfDate; request history is preserved.

For create_approved_leave_requests, each row has employee_id, leave_type_id, start_date, end_date, reason, optional manager_notes, and optional is_half_day / half_day_portion. A half day must use one date, is_half_day: true, and portion FIRST or SECOND. Each request may span at most 366 inclusive calendar days. Normal leave policy, eligibility, notice, balance, overlap and self-approval checks apply. Requests are submitted and approved together; this is not a historical policy waiver. Preview rows for a new batch have id: null; committed rows return stable request IDs and status: approved. Committed requests may notify employees and update payroll.

A validation failure rolls back the whole batch. Known failures return a safe code, optional zero-based rowIndex, and applied: false. A connection failure may have an unknown outcome. Retry an uncertain committed call with the same key and identical rows to obtain its original result; replayed: true identifies a replay. A key that already committed returns its original results and IDs even with dry_run: true, without making further changes. Different input under a used key is rejected. Use a new key for a different batch, and read balances or requests again after applying.

Effects and payroll checks

Management calls can change live Hopshift data. Shift changes and approval decisions may send employee notifications and queue payroll recalculation. publish_schedule controls schedule visibility. Publication can send in-app and push notifications even when notify_employees is false; setting it to true additionally requests email. Correction approval may create or change clock records and shifts.

Queued payroll work is not yet complete. After an action queues creation or recalculation, check the operation status with get_payroll_run or in Hopshift before treating the result as finished.

Payroll access matches the app. A manager with permission for particular employees does not gain visibility of a whole company's payroll. Find the employee's internal ID with list_people, call list_employee_payroll_items with that employee_id, and pass a returned item_id to get_payroll_item. The discovery tool supports page, limit, and optional period_start / period_end filters for payroll periods contained in that date range; it returns only the selected employee's amounts. Company-level reads require company payroll scope. Creating and recalculating payroll require mcp:payroll:write and the app's corresponding Admin authority.

check_payroll_run does not change or approve anything. Its blockers and hasHardBlockers describe publication checks; advisoryReadiness separately reports outstanding attendance work. Advisory readiness is not itself a publication block, and a successful check does not guarantee a later publication will succeed. Publication repeats the current checks, including mandatory Thailand compliance requirements.

Attendance checks include the entire first and last days of the run's pay period in the company's operating timezone, returned as attendanceTimezone. Pending overtime and leave use the payroll calendar dates.

Payroll publication, payslip release and forced attendance-related shift changes must be reviewed and performed in the Hopshift app. MCP does not expose publish_payroll_run, and force_time_update: true / force: true are rejected. App publication retains its approval, current-value, queue and mandatory Thailand document checks. MCP operations are attributed to their actor, OAuth connection or personal key, and tool.

Existing employee integration keys

When MCP is enabled, keys from Group Settings → API Keys with employees:read work at the same MCP URL. They expose only list_employees and get_employee, with the same fields, pagination and stored company restrictions as the Employees API. get_employee takes an internal id from list_employees. These keys cannot call management tools.

Personal management keys expose the management tools above and do not grant the employee REST API's employees:read scope. Use MCP connections for personal keys and API Keys for employee integrations; the two key types have separate lifecycle screens. See Authentication for integration-key scope details.

Test with curl

Set HOPSHIFT_API_KEY to your personal key. Initialize the connection:

curl https://hopshift.app/api/v1/mcp \
  -H "Authorization: Bearer $HOPSHIFT_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"hopshift-curl","version":"1.0.0"}}}'

Use the negotiated protocolVersion in subsequent requests; the examples below use 2025-11-25. Send the initialized notification, discover schemas, then list your workspaces. The notification returns an empty 202 response.

curl https://hopshift.app/api/v1/mcp \
  -H "Authorization: Bearer $HOPSHIFT_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  --data '{"jsonrpc":"2.0","method":"notifications/initialized"}'

curl https://hopshift.app/api/v1/mcp \
  -H "Authorization: Bearer $HOPSHIFT_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  --data '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

curl https://hopshift.app/api/v1/mcp \
  -H "Authorization: Bearer $HOPSHIFT_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  --data '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_workspaces","arguments":{}}}'

After choosing a company, replace the tools/call request body with, for example:

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "list_shifts",
    "arguments": {
      "company_id": "company_id_from_list_workspaces",
      "start_date": "2026-10-26",
      "end_date": "2026-11-01",
      "limit": 50
    }
  }
}

The endpoint returns JSON and creates no persistent MCP session. No MCP-Session-Id is required. Send one JSON-RPC message per POST; batches are rejected. GET and DELETE return 405. See the MCP transport specification.

Limits and errors

Requests are limited to 64 KiB and must finish uploading within 5 seconds. Shared limits across server instances are 200 requests and 30 writes per minute per creator, and 600 requests and 60 writes per minute per group. At most 4 requests per creator and 12 per group can run concurrently; creation, checking and recalculation of payroll share one concurrent slot per group. Additional OAuth connections or keys do not increase these allowances. 429 includes Retry-After in seconds; 503 means the shared limit service is unavailable. Clients may omit Origin; if supplied, it must match the configured site origin. For local development, use http://localhost:3333/api/v1/mcp and set NEXT_PUBLIC_SITE_URL=http://localhost:3333.

404 means MCP is disabled for this deployment. 401 means the credential is missing, invalid, revoked or expired. 403 means the key type or origin is disallowed; individual tools also reject insufficient current permissions. Invalid inputs return protocol or tool errors. Check JSON-RPC error, tool isError, and the returned application status even when HTTP is 200. After an uncertain write result, inspect the current record before retrying; do not assume the change failed.

Overtime reviews require the displayed updatedAt as expected_updated_at and accept pending requests only. Refresh a changed request before deciding.

MCP payroll creation, full-run reads, checks and recalculation accept periods of at most 62 inclusive days. Longer historical periods remain available through payroll summaries and individual items; review and operate longer runs in the app. Individual payroll items return at most 50 lines and report linesTotal and linesTruncated; review additional lines in the app.

Deployment operators

This section is for people running a Hopshift deployment. Users of https://hopshift.app use the connection instructions above.

OAuth is separately disabled by default. Apply the additive OAuth migration and complete browser, SDK, race/replay and access-boundary checks before setting HOPSHIFT_MCP_OAUTH_ENABLED=true alongside the MCP switch. Set a fixed NEXT_PUBLIC_SITE_URL; never use request headers to configure the issuer or resource. Disabling the OAuth switch rejects OAuth access without converting it into API-key authentication. No Supabase OAuth Server activation or additional paid service is required. Keep the OAuth database tables inaccessible to browser roles and preserve refresh replay records until the connection expires or is revoked.

MCP is disabled by default in a new deployment. Set the server-only HOPSHIFT_MCP_ENABLED=true switch only after release checks pass, then deploy the configuration. Until enabled, the endpoint and new personal-key creation return 404; existing keys can still be listed and revoked. To disable MCP, set the switch to false, redeploy and verify the disabled response.

The server also requires HOPSHIFT_SECURITY_BUDGET_URL and HOPSHIFT_SECURITY_BUDGET_TOKEN for its shared Cloudflare Durable Object limits. Use a dedicated service secret and separate local test state. This service secret is not a personal MCP key and must never be entered in an AI client. Missing configuration, service failure or exhausted platform quota blocks protected operations with 503.

Repository maintainers should follow apps/security-budget/README.md for service constraints and plans/mcp-security-audit.md for release checks and recovery. Keep the same persistent namespaces during redeployment; replacing them resets shared enforcement state.