API and MCP Quick-Start Guide

Overview

CrewHR exposes a Model Context Protocol (MCP) endpoint that AI assistants and developer tools can use to interact with scheduling data. This guide covers the three authentication methods and how to get connected quickly.

Authentication Methods at a Glance

Method	Best For	Access Scope	Setup Time
API Key	Admin tools, Claude Code, automations	Full tenant data	2 minutes
OAuth (Authorization Code)	ChatGPT, Claude Desktop, user-facing apps	Individual user data	10 minutes
OAuth + PKCE	Browser-based or mobile apps	Individual user data	10 minutes

Quick Start: API Key

Step 1: Create a Key

Navigate to Settings > Integrations > API Keys and click Create API Key. Copy the key immediately, it is only shown once.

Step 2: Test the Connection

curl -X POST https://app.crewhr.com/api/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: crew_your_key_here" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":1}'

A successful response returns the server capabilities and available tools.

Step 3: Connect to Claude Code

Add to your Claude Code MCP settings (.claude/settings.json or the Claude Code config):

{
  "mcpServers": {
    "crewhr": {
      "url": "https://app.crewhr.com/api/mcp",
      "headers": {
        "X-API-Key": "crew_your_key_here"
      }
    }
  }
}

Claude Code will discover all available tools automatically.

Quick Start: OAuth

OAuth is used when an AI assistant needs to act on behalf of a specific user rather than having full tenant access.

Discovery Endpoints

CrewHR publishes standard OAuth metadata at:

• Authorization Server: https://app.crewhr.com/.well-known/oauth-authorization-server
• Protected Resource: https://app.crewhr.com/.well-known/oauth-protected-resource
• OpenID Configuration: https://app.crewhr.com/.well-known/openid-configuration

MCP-aware clients can auto-discover these endpoints.

OAuth Endpoints

Endpoint	URL
Authorization	https://app.crewhr.com/api/oauth/authorize
Token	https://app.crewhr.com/api/oauth/token
Revocation	https://app.crewhr.com/api/oauth/revoke
User Info	https://app.crewhr.com/api/oauth/userinfo

Available Scopes

Request only the scopes your application needs:

Scope	Description
schedule:read	View work schedules and shifts
schedule:write	Modify schedule drafts and slots
timeoff:read	View time-off requests and balances
timeoff:write	Submit and cancel time-off requests
employee:read	View employee profile information
availability:read	View availability preferences
availability:write	Update availability preferences
timesheet:read	View timesheets and clock-in records
timesheet:write	Clock in/out and manage timesheet entries
mcp:access	Use MCP tools on the user's behalf
offline_access	Receive a refresh token for long-lived access

Authorization Code Flow

Step 1: Redirect the user to authorize:

https://app.crewhr.com/api/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &scope=schedule:read timeoff:read mcp:access
  &state=random_state_value

Step 2: The user signs in and approves permissions on the CrewHR consent screen.

Step 3: CrewHR redirects back to your redirect_uri with a code parameter.

Step 4: Exchange the code for tokens:

curl -X POST https://app.crewhr.com/api/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code&code=AUTH_CODE&redirect_uri=https://yourapp.com/callback&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

Response:

{
  "access_token": "crew_at_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "crew_rt_...",
  "scope": "schedule:read timeoff:read mcp:access"
}

Using PKCE (Public Clients)

For browser-based or mobile apps that cannot securely store a client secret, use PKCE:

1. Generate a random code_verifier (43-128 characters)
2. Compute code_challenge = Base64URL(SHA256(code_verifier))
3. Add code_challenge and code_challenge_method=S256 to the authorization request
4. Include code_verifier in the token exchange request instead of client_secret

Refreshing Tokens

Access tokens expire after 1 hour. Use the refresh token to get a new one:

curl -X POST https://app.crewhr.com/api/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token&refresh_token=crew_rt_...&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

Refresh tokens are rotated on each use. Always store the new refresh token from the response.

Using OAuth Tokens with MCP

Once you have an access token with the mcp:access scope, you can use it to authenticate MCP requests:

curl -X POST https://app.crewhr.com/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer crew_at_your_token_here" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

The MCP server will scope responses to the authenticated user's data and permissions.

Available MCP Tools

Once connected, your AI assistant has access to tools for:

• Schedules - View published schedules, draft schedules, and slot assignments
• Employees - Look up employee information, roles, and locations
• Time Off - View leave requests, balances, and submit new requests
• Timesheets - View clock-in records, approve timesheets
• Availability - Check and update employee availability
• Locations - View location details, sections, and operating hours
• Roles - View role definitions and coverage requirements

The exact tools available depend on the permissions granted via your API key or OAuth scopes.

Rate Limits

• API calls: Rate limited per IP address
• Monthly MCP calls: Limited by your plan tier (visible in Settings > Billing)
• OAuth token requests: 30 per minute per client

Registering an OAuth Client

To register your application as an OAuth client, contact your CrewHR administrator. They will need:

• Application name (shown on the consent screen)
• Redirect URI(s) (where users are sent after authorization)
• Required scopes (what data your application needs)
• Client type (confidential for server apps, public for browser/mobile apps)

FAQ

Q: What is the difference between an API key and an OAuth token?

A: An API key gives full access to your organization's data and never expires (unless deleted). An OAuth token gives access to a specific user's data and expires after 1 hour. Use API keys for admin tools and automations. Use OAuth for user-facing applications.

Q: Can I use both an API key and OAuth at the same time?

A: Yes. The MCP endpoint accepts both. It checks for a Bearer token first, then falls back to the API key. You can use API keys for admin operations and OAuth for user-specific operations.

Q: My token expired. What should I do?

A: If you have a refresh token (granted with the offline_access scope), exchange it for a new access token at the token endpoint. If not, the user will need to re-authorize through the consent flow.

Q: What MCP protocol version does CrewHR support?

A: CrewHR supports the MCP Streamable HTTP transport with protocol version 2025-03-26. Both Claude Code and Claude Desktop support this natively.