SIGN UPLOG IN
X (Twitter)LinkedInGitHubDiscordYouTube

How to integrate SmartHR MCP with Hermes

Connect Hermes 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

Hermes is a 24/7 autonomous agent that lives on your computer or server — it remembers what it learns and evolves as your usage grows.

This guide explains the easiest and most robust way to connect your SmartHR account to Hermes. You can do this through either Composio Connect CLI or Composio Connect MCP. For personal use we recommend the CLI, but you won't go wrong with MCP either.

Also integrate SmartHR with

ChatGPTClaude CoworkAtomic Agent

What is Composio Connect?

Composio Connect is a consumer offering that lets anyone plug 1,500+ applications directly into their agent harness — including Hermes. It can:

  • Search and load tools from relevant toolkits on-demand, reducing context usage.
  • Chain multiple tools to accomplish complex workflows via a remote workbench, without excessive back-and-forth with the LLM.
  • Manage app authentication end-to-end with zero manual overhead.

Integrating SmartHR with Hermes

Using Composio Connect CLI

1. Install the Composio CLI

Run the install script directly, or paste https://composio.dev/hermes into your Hermes chat box to have it installed for you.

bash
curl -fsSL https://composio.dev/install | bash
Hermes authenticating with Composio

2. Authenticate

Once the CLI is installed, ask Hermes to authenticate with Composio.

3. Connect to SmartHR

Ask your agent to connect to SmartHR, or simply request any SmartHR-related task. Hermes will prompt you to authenticate and authorize access.

4. Done. You're all set with a new SmartHR connection.

Using Composio Connect MCP

1. Get your MCP URL and API Key

Go to dashboard.composio.dev and copy your Connect MCP URL and API key.

Copy MCP URL and API key from Composio dashboard

2. Open the Hermes config file

bash
nano ~/.hermes/config.yaml

3. Add the Composio Connect MCP server

bash
mcp_servers:
  composio:
    url: "https://connect.composio.dev/mcp"
    headers:
      x-consumer-api-key: "YOUR_COMPOSIO_API_KEY"
    connect_timeout: 60
    timeout: 180

Save with Ctrl + O, Enter, then exit with Ctrl + X.

4. Restart your Hermes agent

Once restarted, ask your agent to connect to SmartHR or request any SmartHR-related task. It will prompt you to authenticate and authorize access.

5. Done!

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.

Way Forward

With SmartHR connected, Hermes can now act on your behalf whenever it detects a relevant task or you ask it to.

From here, you can extend Hermes further:

  • Connect more apps: Calendar, Slack, Notion, Linear, and hundreds of others are available through the same Composio Connect setup. Each new integration compounds what Hermes can do for you.
  • Build workflows across tools: Once multiple apps are connected, Hermes can chain actions together — turn an email into a calendar invite, a Slack message into a Linear ticket, or a meeting note into a follow-up draft.
  • Let it learn your patterns: The more you use Hermes, the better it gets at anticipating how you'd handle recurring tasks. Give it feedback on drafts and decisions, and it will adapt.

If you run into trouble or want to share what you've built, join the community or check out the Docs for deeper configuration options.

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

Atomic Agent logo

Atomic Agent

Use SmartHR MCP with Atomic Agent

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. Hermes 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