Connect Namely to Claude: Manage HR Resources and Export Reports

If you need to connect Namely to Claude to automate HR workflows, update employee profiles, or extract live organizational reports, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's tool calls and Namely's REST APIs. You can either build and maintain this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL.

If your team uses ChatGPT, check out our guide on /connect-namely-to-chatgpt-sync-profiles-and-organization-data/ or explore our broader architectural overview on /connect-namely-to-ai-agents-automate-employee-feeds-and-job-tiers/.

Giving a Large Language Model (LLM) read and write access to a core Human Resources Information System (HRIS) like Namely is an engineering challenge. You have to handle API token lifecycles, map non-standard JSON schemas to MCP tool definitions, and deal with Namely's strict API quotas and unique data structures. Every time Namely updates an endpoint or changes a field requirement, you have to update your server code, redeploy, and test the integration.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Namely, connect it natively to Claude, and execute complex HR management workflows using natural language.

The Engineering Reality of the Namely API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against Namely's API is painful. You are not just integrating standard CRUD operations - you are dealing with complex HR domain logic, nested data models, and strict system constraints.

If you decide to build a custom Namely MCP server, here are the specific integration challenges you will face:

Decoupled Report Structures Namely's reporting API does not return clean array of objects where each object is a key-value pair of data. Instead, it returns a metadata object, an ordered array of columns, and a separate content array of rows where each row is an array of values positioned to match the column indices. An LLM cannot naturally parse this decoupled format without explicit system prompting. You must build an abstraction layer that explicitly maps these schemas so Claude understands that the third value in row five corresponds to the third column header.

Strict Rate Limiting The Namely profiles API is rate limited to exactly 100 requests per minute. When orchestrating autonomous agents that might rapidly loop through employee records to audit data, hitting this limit is practically guaranteed. It is critical to understand that Truto does not retry, throttle, or apply backoff on rate limit errors. When Namely returns an HTTP 429, Truto passes that error directly to the caller. Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. The caller - in this case, the agent framework operating the LLM - is entirely responsible for reading these headers and executing the retry or backoff logic.

Effective-Dated Fields and Event Restrictions Updating profiles in Namely requires handling effective-dated fields. Modifying a salary, job title, or reporting manager requires specific payload structures that denote when the change takes effect. Furthermore, the Events API has strict operational boundaries: you can manually create an announcement, but other event types (birthdays, anniversaries) are strictly auto-generated by the system and cannot be manually posted via the API. Your MCP tool schemas must strictly enforce these constraints so the LLM does not hallucinate invalid API calls.

Generating the Namely MCP Server

Truto dynamically generates MCP tools based on the active API documentation for your connected integrations. There is no need to write custom handlers for every Namely endpoint. You can generate your Namely MCP server using either the Truto UI or the Truto API.

Method 1: Via the Truto UI

If you prefer a visual interface, you can generate the server directly from the dashboard.

1. Log in to your Truto dashboard and navigate to the Integrated Accounts page.
2. Select your connected Namely account.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Select your desired configuration (e.g., restrict to read-only methods, filter by specific tags, or set an expiration date).
6. Click save and copy the generated MCP server URL.

Method 2: Via the Truto API

For teams building programmatic AI workflows, you can dynamically provision MCP servers on the fly using the Truto REST API. This is ideal for multi-tenant SaaS applications that need to spin up temporary MCP access for background agent tasks.

Make an authenticated POST request to the /integrated-account/:id/mcp endpoint:

curl -X POST https://api.truto.one/integrated-account/YOUR_ACCOUNT_ID/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Namely HR Ops Server",
    "config": {
      "methods": ["read", "write"],
      "tags": ["profiles", "reports", "events"]
    },
    "expires_at": "2025-12-31T23:59:59Z"
  }'

The response will contain the secure URL required to connect your Claude client:

{
  "id": "mcp_abc123",
  "name": "Namely HR Ops Server",
  "expires_at": "2025-12-31T23:59:59.000Z",
  "url": "https://api.truto.one/mcp/tkn_789xyz..."
}

Connecting the MCP Server to Claude

Once you have your MCP server URL, you must connect it to your AI client. The URL encodes the specific integrated account and tool configurations, meaning no additional authentication is required by the client unless you explicitly enforce it.

Option A: Via the Claude Desktop UI

If you are using Claude Desktop or a similar GUI client:

1. Open Claude and navigate to Settings.
2. Click on Integrations (or Connectors depending on your client version).
3. Select Add MCP Server.
4. Paste the Truto MCP URL (e.g., https://api.truto.one/mcp/tkn_789xyz...).
5. Click Add. Claude will immediately initialize the connection and discover the available Namely tools.

Option B: Via Manual Configuration File

If you are configuring Claude Desktop manually or running a headless agent framework, you must update your claude_desktop_config.json file. You will use the standard Server-Sent Events (SSE) transport adapter provided by the MCP specification.

{
  "mcpServers": {
    "namely_hr": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/tkn_789xyz..."
      ]
    }
  }
}

Restart Claude Desktop. The agent will read the config, fetch the JSON-RPC schemas, and the tools will become available in your chat interface.

Namely Hero Tools for Claude

Truto exposes a comprehensive suite of tools for Namely. Below are the highest-leverage operations you can execute using Claude.

list_all_namely_profiles

This tool retrieves employee records from the Namely directory. It supports pagination, sorting, and specific field filters (like job_title, reports_to, or user_status). Because this endpoint is strictly rate limited to 100 requests per minute, Claude will receive standardized IETF rate limit headers if the quota is exceeded.

"Pull a list of all active employee profiles in the engineering department. If you hit a rate limit, pause based on the ratelimit-reset header value before fetching the next page."

update_a_namely_profile_by_id

This tool allows Claude to mutate an employee record. It is highly specific: omitted fields are ignored, meaning you only need to pass the attributes you want to change. It is critical for handling effective-dated updates like salary adjustments or job title changes.

"Update the profile for employee ID 4452. Change their job title to 'Senior Backend Engineer' and ensure the update reflects their new role."

get_single_namely_report_by_id

This is one of the most powerful tools in the integration. It fetches a live Namely report as JSON. Because the API returns decoupled column arrays and row arrays, Claude uses this tool's schema to understand how to map the positional values to their respective headers for analysis.

"Fetch the 'Q3 Attrition' report (ID 889). Analyze the rows against the column headers and summarize the primary reasons for departure listed in the data."

create_a_namely_event

This tool creates an announcement on the Namely home feed. The AI cannot create system events (like birthdays), but it can post rich HTML content for company-wide visibility.

"Draft a welcome announcement for our new hires starting today. Post the event to the Namely home feed using the HTML content we just reviewed."

list_all_namely_teams

This tool fetches the organizational team structure, including linked team categories. It is essential for AI workflows that need to understand reporting hierarchies or audit team distributions without pulling individual profile data.

"Retrieve all teams currently configured in Namely. Identify any teams that do not have an associated email address mapped in the system."

update_a_namely_job_title_by_id

This tool modifies a specific job title label or its parent job tier. It is used heavily during organizational restructuring or when standardizing nomenclature across the HR system.

"Update the job title record for ID 102 from 'Customer Support Rep' to 'Customer Success Specialist', keeping its current parent job tier intact."

For the complete tool inventory, detailed JSON schemas, and parameter requirements, visit the Namely integration page.

Workflows in Action

When you connect Namely to Claude, you graduate from simple data lookups to complex, multi-step HR operations. Here are real-world examples of how agents orchestrate these tools.

Scenario 1: Live HR Data Extraction and Analysis

HR teams often need real-time analysis of custom reports without manually exporting CSVs and formatting spreadsheets. Claude can automate this entirely.

"Fetch the current 'Q4 Compensation' report from Namely. Map the row data to the column headers, calculate the average salary by department, and give me a breakdown of any outliers."

Step-by-step execution:

1. Claude calls get_single_namely_report_by_id with the known report ID.
2. The Truto MCP server executes the proxy API call to Namely.
3. Claude receives the response, internally maps the content row arrays to the columns array based on the schema instructions, and performs the required mathematical analysis before outputting the summary.

sequenceDiagram
  participant Claude as Claude Desktop
  participant Truto as Truto MCP Server
  participant Namely as Namely API

  Claude->>Truto: Call get_single_namely_report_by_id
  Truto->>Namely: Proxy GET /reports/{id}
  Namely-->>Truto: Return decoupled columns and rows
  Truto-->>Claude: JSON response
  Note over Claude: LLM maps row values<br>to column indices
  Claude->>Claude: Calculate averages

Scenario 2: Employee Promotion and Announcement Workflow

When an employee is promoted, multiple steps must happen in sequence: the profile must be updated, the new job title must be applied, and an announcement should be made to the company.

"Employee ID 592 is being promoted to 'Lead Designer'. Update their profile with the new job title, then draft and post a congratulatory announcement to the Namely home feed."

Step-by-step execution:

1. Claude calls update_a_namely_profile_by_id passing the new job_title in the profiles payload.
2. Once the update returns successfully, Claude drafts a brief HTML announcement.
3. Claude calls create_a_namely_event to publish the announcement to the company feed.

flowchart TD
  A["User Prompt<br>Promote employee & announce"] --> B["update_a_namely_profile_by_id"]
  B --> C{"Check Profile<br>Update Status"}
  C -->|"Success"| D["Draft HTML<br>Announcement"]
  D --> E["create_a_namely_event"]

Scenario 3: Bulk Directory Audit and Rate Limit Handling

IT and HR admins frequently audit directory data for missing fields. Because Namely restricts the profiles endpoint to 100 requests per minute, a bulk audit requires the agent to respect HTTP 429 errors.

"Paginate through all Namely profiles and compile a list of employees missing a 'personal_email'. If you hit a rate limit, read the IETF headers and wait before continuing."

Step-by-step execution:

1. Claude calls list_all_namely_profiles with a query filter or simply paginates through the entire directory.
2. Truto proxies the requests. On the 101st request within a minute, Namely rejects it with a 429 Too Many Requests.
3. Truto passes the 429 error and the ratelimit-reset header back to Claude.
4. The agent reads the error, pauses execution until the reset timestamp, and resumes pagination automatically.

Security and Access Control

Exposing an HRIS like Namely to an AI agent requires strict security boundaries. Truto provides several mechanisms to lock down your MCP servers:

• Method Filtering: Use config.methods: ["read"] during server creation to explicitly block the LLM from making POST, PUT, PATCH, or DELETE requests. This ensures Claude can read reports but cannot accidentally alter employee salaries.
• Tag Filtering: Restrict the server to specific domains using config.tags. For example, applying tags: ["events"] ensures the agent can only interact with the company feed and cannot access sensitive profile data.
• Enforced API Token Auth: By setting require_api_token_auth: true, possession of the MCP URL is no longer enough. The client must also pass a valid Truto API token in the Authorization header, adding a required second layer of authentication.
• Auto-Expiring Servers: Set an expires_at datetime. Once the timestamp passes, the underlying KV storage automatically drops the token, and a scheduled alarm cleans up the database record, guaranteeing zero lingering access.

The Path to Autonomous HR Operations

Connecting Namely to Claude via Truto removes the highest barriers to AI integration. You no longer have to build custom OAuth handlers, write explicit error mappings for rate limits, or manually document nested JSON schemas for your LLM context window. The dynamic MCP architecture handles the translation layer, allowing your engineers to focus entirely on prompting and workflow design.

By leveraging tools like get_single_namely_report_by_id and update_a_namely_profile_by_id, your AI agents can execute precise, multi-step HR operations with full visibility into the underlying data structures.