SIGN UPLOG IN
X (Twitter)LinkedInGitHubDiscordYouTube

How to integrate SmartHR MCP with Atomic Agent

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

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

Introduction

Atomic Agent is an open-source AI agent that runs on your machine and supports local models through llama.cpp. Connect it to 1,500+ apps through Composio, including SmartHR.

This guide uses Atomic Agent's built-in Composio integration. You need Atomic Agent v0.5.6 or later, your own Composio API key, and a SmartHR account. See the Atomic Agent documentation for installation instructions.

Also integrate SmartHR with

ChatGPTClaude CoworkHermes

How Atomic Agent connects to SmartHR

Atomic Agent connects to Composio's Tool Router over Streamable HTTP MCP. It discovers the tools needed for your request, and Composio handles account authentication.

Execution and account-connection tools follow Atomic Agent's configured approval policy. Review any approval prompt before allowing an action on your connected account.

Connect SmartHR to Atomic Agent

  1. Sign up or sign in to the Composio dashboard. Copy your API key.
  2. In Atomic Agent, open the Integrations tab and select Composio. Select API key, press e, paste the key, and press Enter. The tools become available immediately, without a restart.
  3. Ask Atomic Agent to do something in SmartHR. It searches Composio for the right tool.
  4. On first use, open the sign-in link returned in the chat. Connect your SmartHR account, then return to Atomic Agent to continue.

Headless setup

Add the following line to ~/.atomic-agent/.env, replacing YOUR_COMPOSIO_API_KEY with your key. Start Atomic Agent after saving the file.

bash
COMPOSIO_API_KEY=YOUR_COMPOSIO_API_KEY

What is the SmartHR MCP server, 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.

Use SmartHR from Atomic Agent

With your account connected, ask Atomic Agent to work with SmartHR in natural language. You can connect more apps through the same Composio integration as you need them.

Visit the Atomic Agent website or inspect the Atomic Agent source code.

Troubleshooting

Why is my API key rejected?

Copy the key directly from the Composio dashboard. Atomic Agent requires ASCII characters because it sends the key in an HTTP header. Remove any extra characters introduced when copying.

Why are Composio tools unavailable after saving a key?

Check that you use Atomic Agent v0.5.6 or later and that Composio is enabled in your configuration. A "composio": { "enabled": false } setting disables the integration while keeping the saved key on disk.

Does Composio have a free plan?

The Hobby plan includes 100,000 tool calls per month. Composio-managed OAuth apps have a lower included allowance. See Composio pricing for the current limits that apply to your connection.

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.

FRAMEWORKS

How to build SmartHR MCP Agent with another framework

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

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. Atomic Agent 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