Connecting AI Assistants to CrewHR (Claude, ChatGPT, and More)

What Does "Connecting an AI Assistant" Mean?

When you connect an AI assistant to CrewHR, you are giving it permission to read and manage your scheduling data on your behalf. Instead of logging into the CrewHR dashboard every time you want to check a schedule or request time off, you can simply ask your AI assistant to do it for you.

For example, you could say:

"Show me who is working this Friday at our Blackrock location"
"Request next Monday off for me"
"What shifts do I have next week?"

The AI assistant communicates with CrewHR in the background, retrieves the information, and responds in plain language.

How It Works (The Simple Version)

There are two ways an AI assistant can connect to CrewHR:

API Keys (for administrators) - A secret password that gives the AI full access to your organization's data. Best for admin tools and automations.
Sign-In Authorization (OAuth) - The AI redirects you to CrewHR's sign-in page, you approve specific permissions, and the AI gets limited access to only your data. Best for personal assistants like ChatGPT or Claude.

Think of it like this: an API key is like giving someone a master key to the building, while OAuth is like a visitor badge that only opens certain doors and expires after a set time.

Method 1: API Keys (Admin Access)

API keys give an AI assistant full access to your organization's CrewHR data. This is ideal for administrators who want to use AI tools like Claude Code or custom automations.

Creating an API Key

Navigate to Settings > Integrations > API Keys
Click Create API Key
Give the key a descriptive name (e.g., "Claude Desktop" or "Scheduling Bot")
Select the permissions you want to grant:
- Read - View schedules, employees, and settings
- Write - Create and modify schedules, assign shifts
- All - Full access to all features
Click Create
Copy the key immediately. It starts with crew_ and will only be shown once

Using an API Key with Claude Code

Claude Code can connect to CrewHR directly using your API key. Add this to your Claude Code MCP configuration:

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

Once connected, Claude Code can read your schedules, create drafts, manage employees, and more through natural conversation.

Using an API Key with Other Tools

Any tool that supports the MCP (Model Context Protocol) standard or REST APIs can use your API key. Include it as an X-API-Key header in requests to https://app.crewhr.com/api/mcp.

API Key Security Tips

Never share your API key publicly or commit it to code repositories
Create separate keys for each tool or integration
Use the minimum permissions needed for each key
Rotate keys periodically by creating a new one and deleting the old one
If a key is compromised, delete it immediately from Settings > Integrations

Method 2: Sign-In Authorization (OAuth)

OAuth lets an AI assistant access your personal CrewHR data without ever seeing your password. You sign in to CrewHR directly, approve what the assistant can access, and CrewHR gives it a temporary pass.

This is the method used by ChatGPT Custom GPTs and Claude when they connect on behalf of individual users.

How the Sign-In Flow Works

You ask the AI assistant to do something with CrewHR (e.g., "Show me my schedule")
The assistant opens a CrewHR sign-in page in your browser
You sign in with your normal CrewHR credentials
CrewHR shows you what the assistant is requesting access to (e.g., "View your work schedule")
You click Authorize to approve, or Deny to reject
The assistant receives a temporary access token and can now help you

You only need to do this once. The assistant remembers your authorization until it expires or you revoke it.

What Permissions Can You Grant?

When you authorize an AI assistant, you choose exactly what it can access:

View your work schedule - See your shifts and assignments
View your time-off requests - Check balances and request status
Submit time-off requests - Request days off on your behalf
View your employee profile - See your name, role, and location
View your availability - Check your availability preferences
Update your availability - Change when you are available to work
View your timesheets - See clock-in and clock-out records
Clock in and out - Manage your time tracking
Use AI tools on your behalf - Enable the full AI assistant experience

You will always see exactly what is being requested before you approve.

Revoking Access

If you want to disconnect an AI assistant:

Navigate to Settings > Integrations > Connected Apps
Find the assistant you want to disconnect
Click Revoke Access

The assistant will immediately lose access and will need to request authorization again if you want to reconnect.

Understanding MCP (Model Context Protocol)

You may see the term "MCP" mentioned when connecting AI assistants. MCP is a standard protocol that lets AI assistants communicate with apps like CrewHR in a structured way.

Think of MCP as a universal translator. Instead of each AI assistant needing custom code to work with CrewHR, MCP provides a common language they all understand. This means:

Claude (by Anthropic) supports MCP natively
ChatGPT (by OpenAI) can connect through Custom Actions
Other AI tools that support MCP can connect without any custom setup

As a user, you do not need to understand the technical details of MCP. Just know that when an AI tool says it "supports MCP," it means it can connect to CrewHR.

Which Method Should I Use?

Scenario	Recommended Method
You are an admin setting up an AI tool for your organization	API Key
You are using Claude Code for development or automation	API Key
You want ChatGPT to help you manage your personal schedule	OAuth (Sign-In)
You are an employee who wants AI help with time-off requests	OAuth (Sign-In)
You are building a custom integration or bot	API Key
You want to give an AI limited, temporary access	OAuth (Sign-In)

Setting Up ChatGPT with CrewHR

To use CrewHR with a ChatGPT Custom GPT:

Open the GPT Builder in ChatGPT
Under Actions, add a new action
Set the authentication type to OAuth
Enter the following URLs:
- Authorization URL: https://app.crewhr.com/api/oauth/authorize
- Token URL: https://app.crewhr.com/api/oauth/token
Enter the Client ID and Client Secret provided by your CrewHR administrator
Set the scopes you need (e.g., schedule:read timeoff:read employee:read)
Save and test the connection

When users interact with your GPT, they will be prompted to sign in to CrewHR and authorize access.

Setting Up Claude with CrewHR

Claude Code (Terminal)

Add CrewHR as an MCP server in your Claude Code configuration:

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

Claude Desktop

Open Claude Desktop settings
Navigate to the MCP servers section
Add a new server with the URL https://app.crewhr.com/api/mcp
When prompted, sign in to your CrewHR account and authorize access

Claude will automatically discover what actions are available and can help you manage schedules, view employee information, handle time-off requests, and more.

Troubleshooting

"Authorization failed" or "Invalid API key"

Double-check that you copied the full API key (it starts with crew_)
Verify the key has not been deleted or disabled in Settings > Integrations
Make sure the key has the correct permissions for what you are trying to do

"Session expired" or "Please sign in again"

OAuth access tokens expire after 1 hour for security
Simply ask the AI assistant to try again and it will refresh the connection automatically
If it keeps failing, revoke the connection and re-authorize

"Insufficient permissions"

The AI assistant is trying to do something it was not authorized to do
Revoke and re-authorize with the additional permissions needed
For API keys, check the permission level in Settings > Integrations

The AI assistant cannot find my data

Verify you are signed into the correct CrewHR account
Check that your organization has the data the assistant is looking for (e.g., published schedules)
Try asking the assistant a simpler question first (e.g., "What is my name in CrewHR?")

FAQ

Q: Is my data safe when I connect an AI assistant?

A: Yes. AI assistants only access the data you explicitly authorize. OAuth connections use temporary tokens that expire, and you can revoke access at any time. Your password is never shared with the AI assistant.

Q: Can my employer see that I connected an AI assistant?

A: Administrators can see which integrations are active for the organization. They cannot see the contents of your conversations with the AI assistant.

Q: Do I need to pay extra for AI integrations?

A: AI integrations are included with your CrewHR plan. However, the AI assistant itself (like ChatGPT Plus or Claude Pro) may require its own subscription.

Q: Can I connect multiple AI assistants at the same time?

A: Yes. You can have multiple AI assistants connected simultaneously, each with their own permissions. You can manage all connections from Settings > Integrations.

Q: What happens if I change my CrewHR password?

A: Existing AI connections will continue to work because they use separate access tokens, not your password. If you want to disconnect everything for security, revoke all connections from your integrations settings.