SIGN UPLOG IN
X (Twitter)LinkedInGitHubDiscordYouTube

SmartHR MCP server for AI agents and assistants

Securely connect your AI agents and chatbots (Claude, ChatGPT, Cursor, etc) with SmartHR MCP or direct API to read employee records, query organization data, review payroll documents, and manage HR workflows through natural language.

Get started for freeGet a demo
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

Try SmartHR now

Type what you want done — sign in and watch it run live in the Tool Router playground.

TOOL ROUTER PLAYGROUND
SmartHR
Try asking
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.

SETUP GUIDE

Connect SmartHR MCP Tool with your Agent

1

Install Composio

typescript
npm install @composio/core ai @ai-sdk/mcp @ai-sdk/openai
Install the Composio SDK and your agent framework
2

Create a session with MCP enabled

typescript
import { Composio } from "@composio/core";

const composio = new Composio();
const { mcp } = await composio.create("your-user-id", {
  toolkits: ["smarthr"],
  mcp: true,
});
Create a session scoped to SmartHR and read its MCP URL and headers
3

Connect your agent to the MCP server

typescript
import { createMCPClient } from "@ai-sdk/mcp";
import { openai } from "@ai-sdk/openai";
import { generateText, stepCountIs } from "ai";

const client = await createMCPClient({
  transport: { type: "http", url: mcp.url, headers: mcp.headers },
});

const { text } = await generateText({
  model: openai("gpt-5.6-sol"),
  tools: await client.tools(),
  prompt: "List all employees in SmartHR and show their names and employment status.",
  stopWhen: stepCountIs(10),
});

console.log(text);
await client.close();
Pass the session's MCP URL and headers to your agent and run a SmartHR request
SETUP GUIDE

Connect SmartHR API Tool with your Agent

1

Install Composio

typescript
npm install @composio/core @composio/openai openai
Install the Composio SDK, the OpenAI provider, and the OpenAI SDK
2

Create a Composio session

typescript
import OpenAI from "openai";
import { Composio } from "@composio/core";
import { OpenAIResponsesProvider } from "@composio/openai";

const composio = new Composio({ provider: new OpenAIResponsesProvider() });
const client = new OpenAI();

const session = await composio.create("your-user-id", { toolkits: ["smarthr"] });
const tools = await session.tools();
Initialize Composio with the OpenAI Responses provider and create a session scoped to SmartHR
3

Run SmartHR tools with your agent

typescript
let response = await client.responses.create({
  model: "gpt-5.6-sol",
  tools,
  input: [{ role: "user", content: "List all employees in SmartHR and show their names and employment status." }],
});

while (response.output.some((o) => o.type === "function_call")) {
  const outputs = await composio.provider.handleToolCalls(session, response.output);
  response = await client.responses.create({
    model: "gpt-5.6-sol",
    tools,
    previous_response_id: response.id,
    input: outputs,
  });
}

console.log(response.output_text);
Send a request, execute the SmartHR tool calls through the session, and print the final answer

Why Use Composio?

AI Native SmartHR Integration

  • Supports both SmartHR MCP and direct API based integrations
  • Structured, LLM-friendly schemas for reliable employee and organization data access
  • Rich coverage for reading, writing, and querying your SmartHR data

Managed Auth

  • Securely connect SmartHR with API key authentication
  • Central place to manage, scope, and revoke SmartHR access
  • Per user and per environment credentials instead of hard-coded keys

Agent Optimized Design

  • Tools are tuned using real error and success rates to improve reliability over time
  • Comprehensive execution logs so you always know what ran, when, and on whose behalf

Enterprise Grade Security

  • Fine-grained RBAC so you control which agents and users can access SmartHR
  • Scoped, least privilege access to employee and organization resources
  • Full audit trail of agent actions to support review and compliance
FRAMEWORKS

Use SmartHR with any AI Agent Framework

Choose a Framework you want to connect SmartHR with

ChatGPT logo

ChatGPT

Use SmartHR MCP with ChatGPT

Claude Cowork logo

Claude Cowork

Use SmartHR MCP with Claude Cowork

Hermes logo

Hermes

Use SmartHR MCP with Hermes

Atomic Agent logo

Atomic Agent

Use SmartHR MCP with Atomic Agent

Rolling this out across your team?

Give your team centralized access control across every framework with Composio’s MCP Gateway.

EXPLORE MCP GATEWAY
FAQ

Frequently asked questions

Yes, SmartHR requires you to configure your own API key credentials. Once set up, Composio handles secure credential storage and API request handling for you.

Yes! Composio's Tool Router enables agents to use multiple toolkits. Learn more.

Yes. Composio is SOC 2 Type II compliant and is built to keep your SmartHR connection and credentials secure. OAuth tokens and API keys are encrypted, and sensitive customer data is protected at rest and in transit.

Composio also undergoes independent security testing and continuously monitors its systems for security threats. You can review the latest reports and policies in the Composio Trust Center.

Composio maintains and updates all toolkit integrations automatically, so your agents always work with the latest API versions.

Create the key in your SmartHR account settings, then paste it once on Composio's connection page. Composio stores it encrypted and uses it only for the SmartHR actions your agent runs. Nobody else in your workspace can read it, and you can revoke it inside SmartHR at any time.

When you connect a SmartHR account through Composio, every action runs under that account, so anything the agent creates, sends, or changes shows up in SmartHR as done by you. Keep an approval step in your prompt for actions with side effects, such as sending or deleting, and have the agent draft first.

Whatever the credentials you connect allow inside SmartHR. If SmartHR lets you scope a key to specific permissions, create a scoped one so the agent can only do what you intend. You can revoke the key inside SmartHR at any time.

Yes. Composio supports multiple connected accounts for the same app, and that works in Claude, ChatGPT, or any other assistant you connect through Composio. Give each SmartHR connection a name such as work or personal, and the assistant uses the one you mention in the request. Each account keeps its own credentials and nothing is merged.

The connection stops working the moment SmartHR rejects the old key. Create a new key in SmartHR and reconnect the account from the Composio dashboard or by asking your agent to reconnect SmartHR. Nothing else changes.

Composio's free Hobby plan includes 100,000 tool calls per month with no credit card, which covers most personal SmartHR use. Paid plans add higher limits and team features. Your SmartHR plan and its API limits still apply as usual.

Built-in connectors usually give one AI access to a limited set of apps. Many people use Composio because it lets their AI connect to more apps than it normally supports, or connect to multiple accounts for the same app (e.g. connect Claude to multiple SmartHR accounts).

With Composio, you connect SmartHR once and then use it across different AI assistants without setting it up separately in each one. Connect your apps to Composio once, then connect Composio to whichever AI you use, whether that's Claude, ChatGPT, Hermes, or your own custom assistant.

Start with SmartHR.It takes 30 seconds.

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

Start building