How to connect SmartHR to Claude

Connect Claude Web, Desktop and Cowork to SmartHR MCP. List employees with missing profile fields, find recently updated employee records, and more using natural language, with authentication handled for you.

SmartHR logoSmartHR
Api Key

SmartHR is a cloud human resources platform for employee records, organization data, payroll documents, and HR workflows. It helps teams manage core HR operations in one secure, centralized workspace.

116 Tools

Introduction

Claude is Anthropic's AI assistant, available on the web, in the desktop app, and on mobile. Cowork is its agent for knowledge work, and it runs on all of those surfaces too. Connected to your apps, Claude can work with your files and services to accomplish complex tasks on your behalf.

This guide walks you through the easiest and most secure way to connect your SmartHR account to Claude via Composio Connect, enabling it to list employees with missing profile fields, find recently updated employee records, review organization data for inactive employees, and more such actions on your behalf without compromising your account security.

Setup is the same on Claude Web, Desktop, and Cowork, and you only need to do it once. The connector is tied to your account, so it's available in all three.

Also integrate SmartHR with

Connecting SmartHR to Claude Web, Desktop, and Cowork

Two ways to add the Composio connector. Pick whichever you prefer.

1. Add with one click

Click the button. Claude opens with the Composio connector filled in. Click Add, then go to step 2.

Add to Claude

Add manually

In Claude Desktop, click Customize in the left sidebar, then select Connectors and click the + icon at the top.

Claude Desktop connectors screen with Add custom connector selected

Click Add custom connector and paste in the Composio MCP server URL:

bash
https://connect.composio.dev/mcp
Add custom connector dialog with Composio MCP server URL

2. Authorize in your browser

Click Connect. You'll be redirected to a browser window where you can authorize Composio to continue.

Composio authorization screen for Claude Web, Desktop, and Cowork

3. Connect your SmartHR account

Back in Claude, ask it to connect to SmartHR or give it any SmartHR-related task.

For example, ask Claude to:

  • "List employees with missing profile fields"
  • "Find recently updated employee records"
  • "Review organization data for inactive employees"

It will prompt you to authenticate and authorize access.

That's it. Composio's tools are now available in Claude, and your SmartHR account is ready to use.

What is the SmartHR Claude Connector, and what's possible with it?

The SmartHR MCP server is an implementation of the Model Context Protocol that connects your AI agent and assistants like Claude, Cursor, etc directly to your SmartHR account. It provides structured and secure access to employee records, departments, payroll data, tax withholding documents, user SAML configurations, webhooks, and batch jobs, so your agent can create employee and organization records, retrieve HR data, manage payroll and tax documents, configure access settings, and handle background job files on your behalf.

  • Employee and organization management: Have your agent create and retrieve employee records, add employee dependents, create departments, and define employment types, grades, job categories, and job titles.
  • Payroll and payslip administration: Let your agent create payroll groups, add individual or bulk payslips, finalize payroll, retrieve payroll attachments, and remove payroll records when needed.
  • Tax document handling: Direct your agent to create tax withholding groups and employee tax withholding slips, then delete those records when they are no longer required.
  • Access and event configuration: Instruct your agent to create, enable, disable, or delete user SAML configurations and set up or remove SmartHR webhooks for employee and dependent events.
  • Background job and file retrieval: Have your agent check batch job details and download files attached to completed SmartHR background jobs.

Troubleshooting

1. Why does Claude not use the Composio connector for SmartHR?

The connector can show as connected, but Claude must use it in each SmartHR conversation.

  • Click + at the lower left of the chat, or type /.
  • Hover Connectors.
  • Turn on Composio.
  • Ask Claude to connect to SmartHR again.

2. Why does Claude show an MCP server error before SmartHR connects?

Claude can show Couldn't reach the MCP server or Authorization with the MCP server failed when you add the connector for SmartHR.

  • Check that the connector URL is https://connect.composio.dev/mcp.
  • Connectors run from Anthropic's cloud, so your device network is usually not the problem.
  • Add the connector again from Customize > Connectors, then ask Claude to connect SmartHR.
  • If it fails again, send the error and the ofid_ reference id to support@composio.dev.

3. Why does the SmartHR authorization link not work?

The Composio connector is one server. Your SmartHR account connects separately when Claude asks for it.

  • If the browser does not open, or the link expires, ask Claude to retry the SmartHR connection.
  • Composio creates a fresh SmartHR authorization link.
  • Open that link in your browser and finish the SmartHR sign-in.

4. Why do SmartHR actions fail after they worked before?

The SmartHR connection can expire or lose permission.

  • Ask Claude to inspect the SmartHR connection.
  • If the connection is unhealthy, disconnect it when Claude prompts you.
  • Reconnect the SmartHR account and retry the action.
  • If Claude shows a permission prompt, approve it before Claude changes data in SmartHR.
  • If the action still fails with a permission error, check that the connected account has that permission in SmartHR itself.

5. How do I switch to a different SmartHR account?

Claude can manage the SmartHR connection for you.

  • Ask Claude to disconnect or delete the current SmartHR account.
  • Ask Claude to connect SmartHR again.
  • Open the new Composio authorization link for SmartHR.
  • Sign in with the other SmartHR account in the browser.
  • After the account connects, ask Claude to retry the SmartHR task.

6. Why is my SmartHR connection missing in Claude Desktop or on a Team plan?

The connector belongs to your Claude account, so your SmartHR connection works in Claude Web, Desktop, and Cowork.

  • In Claude Desktop, open Customize > Connectors.
  • Next to Composio, click ⋮ and click Clear cache.
  • If SmartHR tools still do not appear, click ⋮, disconnect, remove the connector, and add it again.
  • On Team or Enterprise, an Owner or Primary Owner must enable the connector before you can connect SmartHR.
TOOLS

Supported Tools

Every SmartHR action and event your agent gets out of the box.

Bulk Create Payslips

Create up to 100 sensitive payslip entries in one SmartHR payroll group.

Create Department

Create a SmartHR department.

Create Employee

Create an employee using the documented SmartHR employee fields.

Create Employee Custom Field Template

Create an employee custom-field template.

Create Employee Custom Field Template Group

Create an employee custom-field template group.

Create Employee Dependent

Create a dependent for one employee using the documented family fields.

Create Employment Type

Create a SmartHR employment type.

Create Grade

Create a SmartHR grade.

Create Job Category

Create a SmartHR job category.

Create Job Title

Create a SmartHR job title.

Create Payroll

Create a sensitive SmartHR payroll group.

Create Payslip

Create a sensitive employee payslip in one SmartHR payroll group.

Create Recruitment Type

Create a SmartHR recruitment type.

Create Tax Withholding

Create a sensitive SmartHR tax-withholding group in the unconfirmed state.

Create Tax Withholding Slip

Create a file-backed or field-backed sensitive tax-withholding slip for an employee in one SmartHR tax-withholding group.

Create User SAML Configuration

Create the SAML SSO account configuration for one SmartHR user.

Create Webhook

Create a SmartHR webhook configuration for future employee and dependent events.

Delete Employee

Permanently delete one employee by SmartHR employee ID.

Delete Employee Custom Field Template

Delete one employee custom-field template by ID.

Delete Employee Custom Field Template Group

Delete one employee custom-field template group by ID.

Delete Employee Dependent

Permanently delete one dependent and their sensitive family data from an employee record.

Delete Employment Type

Delete one SmartHR employment type by ID.

Delete Grade

Delete one SmartHR grade by ID.

Delete Job Category

Delete one SmartHR job category by ID.

Delete Job Title

Delete one SmartHR job title by ID.

Delete Payroll

Permanently delete one sensitive SmartHR payroll group by ID.

Delete Payslip

Permanently delete one sensitive SmartHR payslip from its payroll group.

Delete Recruitment Type

Delete one SmartHR recruitment type by ID.

Delete Tax Withholding

Permanently delete one sensitive SmartHR tax-withholding group by ID.

Delete Tax Withholding Slip

Permanently delete one sensitive SmartHR tax-withholding slip from its tax-withholding group.

Delete User SAML Configuration

Delete the SAML SSO account configuration for one SmartHR user.

Delete Webhook

Permanently delete one SmartHR webhook configuration by ID.

Disable User SAML Configuration

Disable the SAML SSO account configuration for one SmartHR user.

Discontinue Department

Irreversibly discontinue one SmartHR department as of its final active date.

Download Batch Job Attachment

Download the binary file for a SmartHR batch-job attachment.

Enable User SAML Configuration

Enable the SAML SSO account configuration for one SmartHR user.

Finalize Payroll

Finalize one sensitive SmartHR payroll group.

Get Batch Job

Get one SmartHR background batch job by ID, optionally embedding its attachments.

Get Department

Get one SmartHR department by its department ID.

Get Employee

Get one employee by SmartHR employee ID, with optional comma-separated field selection.

Get Employee Custom Field Template

Get one employee custom-field template by ID.

Get Employee Custom Field Template Group

Get one employee custom-field template group by ID.

Get Employee Dependent

Get one dependent belonging to an employee.

Get Employee Input Form

Get one SmartHR employee information-collection form by ID, preserving its nested field groups, fields, and embedded custom-field definitions.

Get Employment Type

Get one SmartHR employment type by its employment type ID.

Get Grade

Get one SmartHR grade by its grade ID.

Get Job Category

Get one SmartHR job category by its job category ID.

Get Job Title

Get one SmartHR job title by its job title ID.

Get Mail Format

Get one SmartHR mail format by ID, optionally embedding the employee information-collection forms that use it.

Get Payment Period

Get one SmartHR payroll payment period by its payment period ID.

Get Payroll

Get one sensitive SmartHR payroll group by ID.

Get Payslip

Get one highly sensitive SmartHR payslip from a payroll group.

Get Recruitment Type

Get one SmartHR recruitment type by its recruitment type ID.

Get Tax Withholding

Get one highly sensitive SmartHR tax-withholding group by ID.

Get Tax Withholding Slip

Get one highly sensitive SmartHR tax-withholding slip from a tax-withholding group.

Get User

Get one SmartHR user account by user ID with an optional related object embedded in the response.

Get User SAML Configuration

Get the SAML SSO account configuration for one SmartHR user.

Get Webhook

Get one SmartHR webhook configuration by webhook ID.

Invite Employee

Send the documented SmartHR invitation to one employee's configured email address.

List Bank Account Settings

List one page of SmartHR bank-account setting definitions.

List Batch Jobs

List one page of SmartHR background batch jobs.

List Business Establishments

List one page of SmartHR business establishments, optionally embedding the social insurance representative, labor insurance representative, or company.

List Companies

List one page of SmartHR companies with an optional embedded owner.

List Departments

List one page of SmartHR departments using the documented code and sort filters.

List Dependent Custom Field Templates

List one page of SmartHR custom-field templates for employee dependents.

List Dependent Relations

List one page of configured SmartHR dependent relationship types.

List Employee Custom Field Template Groups

List one page of employee custom-field template groups.

List Employee Custom Field Templates

List one page of SmartHR employee custom-field templates.

List Employee Dependents

List one page of sensitive family and dependent records for a SmartHR employee.

List Employee Input Forms

List one page of SmartHR employee information-collection forms with their nested field definitions.

List Employee Maternity and Childcare Leaves

List one page of sensitive maternity and childcare leave records for a SmartHR employee.

List Employees

List one page of employees matching SmartHR's documented employee filters.

List Employment Types

List one page of SmartHR employment types.

List Grades

List one page of SmartHR grades.

List Job Categories

List one page of SmartHR job categories.

List Job Titles

List one page of SmartHR job titles using the documented sort option.

List Mail Formats

List one page of SmartHR mail formats.

List Payment Periods

List one page of SmartHR payroll payment periods.

List Payrolls

List one page of sensitive SmartHR payroll groups using payment-date and payment-type filters.

List Payslips

List one page of highly sensitive SmartHR payslips in a payroll group.

List Recruitment Types

List one page of SmartHR recruitment types.

List Tax Withholdings

List one page of sensitive SmartHR tax-withholding groups.

List Tax Withholding Slips

List one page of sensitive tax-withholding slips in a SmartHR tax-withholding group.

List Users

List one page of SmartHR user accounts with the documented sort and embed options, invitation status, role, and email-delivery status.

List Webhooks

List one page of SmartHR webhook configurations.

Partially Update Department

Partially update a SmartHR department by ID.

Partially Update Employee Custom Field Template

Partially update an employee custom-field template.

Partially Update Employment Type

Partially update a SmartHR employment type by ID.

Partially Update Payroll

Partially update the administrator-facing and employee-facing names of a sensitive SmartHR payroll group by ID.

Partially Update User SAML Configuration

Partially update the SAML SSO account configuration for one SmartHR user.

Partially Update Webhook

Partially update a SmartHR webhook by ID.

Publish Payroll

Irreversibly publish one sensitive SmartHR payroll group immediately or at a scheduled time within one month, optionally notifying employees.

Remove Employee Departments

Remove all department assignments from one employee using the documented SmartHR endpoint.

Reopen Payroll

Reopen one sensitive SmartHR payroll group.

Replace Department

Replace a SmartHR department through PUT.

Replace Employee Custom Field Template

Replace an employee custom-field template through the documented PUT operation.

Replace Employee Custom Field Template Group

Replace an employee custom-field template group through the documented PUT operation.

Replace Employment Type

Replace a SmartHR employment type through PUT.

Replace Grade

Replace a SmartHR grade by ID using full PUT semantics.

Replace Job Category

Replace a SmartHR job category by ID using full PUT semantics.

Replace Job Title

Replace a SmartHR job title by ID using full PUT semantics.

Replace Recruitment Type

Replace a SmartHR recruitment type by ID using full PUT semantics.

Replace Tax Withholding

Replace a sensitive SmartHR tax-withholding group by ID using full PUT semantics.

Replace Webhook

Replace a SmartHR webhook through PUT.

Start Dependent Import Job

Start an asynchronous SmartHR dependent-data import from a Base64-encoded CSV or Excel file.

Start Employee Export Job

Start a SmartHR background job that exports employee information using an existing custom download format.

Start Employee Import Job

Start a SmartHR background job that inserts or updates employees from a sensitive base64-encoded CSV or Excel file.

Update Employee

Update the supplied documented fields of one employee by SmartHR employee ID.

Update Employee Custom Field Template Group

Update one or more supplied fields of an employee custom-field template group.

Update Employee Dependent

Update the supplied fields of one dependent belonging to an employee.

Update Grade

Update the supplied fields of a SmartHR grade by ID.

Update Job Category

Update the supplied fields of a SmartHR job category by ID.

Update Job Title

Update the supplied fields of a SmartHR job title by ID.

Update Recruitment Type

Update a SmartHR recruitment type by ID.

Update Tax Withholding

Update the supplied fields of a sensitive SmartHR tax-withholding group by ID.

Update Tax Withholding Slip

Update a sensitive SmartHR tax-withholding slip.

FAQ

Frequently asked questions

With a standalone SmartHR MCP server, the agents and LLMs can only access a fixed set of SmartHR tools tied to that server. However, with the Composio Tool Router, agents can dynamically load tools from SmartHR and many other apps based on the task at hand, all through a single MCP endpoint.

Yes, you can. Claude Cowork fully supports MCP integration. You get structured tool calling, message history handling, and model orchestration while Tool Router takes care of discovering and serving the right SmartHR tools.

Yes, absolutely. You can configure which SmartHR scopes and actions are allowed when connecting your account to Composio. You can also bring your own OAuth credentials or API configuration so you keep full control over what the agent can do.

All sensitive data such as tokens, keys, and configuration is fully encrypted at rest and in transit. Composio is SOC 2 Type 2 compliant and follows strict security practices so your SmartHR data and credentials are handled as safely as possible.

Start with SmartHR.It takes 30 seconds.

Managed auth, hosted MCP servers, and every SmartHR tool your agent needs.Free to start.

Start building