Connect Namely to ChatGPT: Sync Profiles and Organization Data

If you want to connect Namely to ChatGPT so your AI agents can read employee profiles, update job titles, pull live organizational reports, and announce new hires, you need a Model Context Protocol (MCP) server. This server acts as a translation layer, taking JSON-RPC tool calls from the Large Language Model (LLM) and converting them into authenticated REST API requests against Namely's HRIS infrastructure.

If your team uses Claude, check out our guide on connecting Namely to Claude or explore our broader architectural overview on connecting Namely to AI Agents.

Giving an AI agent read and write access to a core Human Resources Information System (HRIS) is an engineering challenge fraught with edge cases. You have to handle complex relational grouping, parse matrix-style report payloads, and strictly respect rate limits. You can either build, host, and maintain a custom MCP server for Namely yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL in seconds.

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

The Engineering Reality of the Namely API

Building a custom MCP server means you own the entire integration lifecycle. While the open MCP standard provides a predictable interface for ChatGPT to discover tools, executing those tools against Namely's specific API design requires significant translation logic.

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

The Matrix Payload of Namely Reports

When an LLM calls an endpoint like /api/v1/reports/:id, it expects standard JSON objects (e.g., [{"name": "John", "title": "Engineer"}]). Namely does not return reports this way. Instead, the API returns a metadata block, an ordered columns array, and a content array of arrays. The value at content [i][1] corresponds to the header at columns [1]. If you pipe this directly to an LLM, the model often hallucinates data mapping. Your MCP server must include specific prompt instructions in the tool description to force the LLM to map the matrix correctly, or you must build middleware to reshape the payload into standard JSON objects before returning it to the agent.

Group Types vs Groups vs Teams

Namely's organizational structure is highly normalized. A standard SaaS API might have a /departments endpoint. Namely abstracts this into group_types (which define categories like "Department" or "Office Location"), groups (the actual entities, like "Engineering" or "New York"), and teams (cross-functional squads). If an LLM needs to update everyone in the "Engineering" department, your MCP server must expose multiple tools and teach the LLM to traverse this specific relational hierarchy.

Rate Limits and the 429 Cascade

Namely enforces a strict limit of 100 requests per minute per token. Because AI agents utilize parallel tool calling (often dispatching 10-20 requests simultaneously to enrich profiles), they can easily blow past this limit in under 10 seconds. 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 and normalizes the upstream rate limit info into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF spec. If you are building the integration, your MCP client must catch these 429 errors, parse the reset window, and manually back off.

How to Generate a Namely MCP Server via Truto

Truto abstracts away the payload normalization and OAuth lifecycle management. By connecting Namely as an Integrated Account in Truto, you can generate an MCP server dynamically.

There are two ways to spin up this server.

Method 1: Via the Truto UI

This is the fastest method for internal tooling and testing.

1. Log into your Truto dashboard and navigate to Integrated Accounts.
2. Click on your active Namely connection to open the account page.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Select your desired configuration. For example, you can limit the server to read methods only, or restrict access to specific tags like profiles or reports.
6. Copy the generated MCP server URL (it will look like https://api.truto.one/mcp/<token>). Treat this URL like a production secret.

Method 2: Via the Truto API

If you are building a multi-tenant AI application and need to programmatically provision MCP servers for your customers, use the Truto REST API.

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

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

The API will return a JSON response containing the url. This single URL handles the JSON-RPC routing and authenticates the specific Namely tenant account.

How to Connect the MCP Server to ChatGPT

Once you have the https://api.truto.one/mcp/<token> URL, you need to register it as a tool provider for your AI agent.

Method 1: Via the ChatGPT UI

If you are using ChatGPT Pro, Plus, Business, Enterprise, or Education, you can add the server directly via the interface.

1. In ChatGPT, open Settings -> Apps -> Advanced settings.
2. Toggle Developer mode to ON.
3. Under MCP servers / Custom connectors, click Add new server.
4. Enter a name (e.g., "Namely HRIS").
5. Paste your Truto MCP server URL into the Server URL field.
6. Click Save. ChatGPT will immediately ping the endpoint, execute the handshake, and list the available Namely tools.

Method 2: Via Manual Configuration (Custom Agents)

If you are running a custom LangGraph, CrewAI, or local agent architecture, you connect via Server-Sent Events (SSE). You can bridge the remote Truto URL into your local environment using the standard @modelcontextprotocol/server-sse package.

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

Hero Tools for Namely Automation

Truto automatically generates MCP tools from Namely's API documentation, flattening query parameters and JSON bodies into a single arguments namespace. Here are the highest-leverage operations your ChatGPT agent can perform out of the box.

List All Namely Profiles

This tool pulls employee directories. It supports pagination (page and per_page up to 50) and robust filtering. It returns the profile's ID, creation timestamps, and core identifying information.

"Pull a list of all active profiles currently holding the job title 'Account Executive'. Limit the results to the first 50 people."

Update a Namely Profile by ID

This tool modifies existing employee records. It behaves like a PATCH request - you only need to pass the fields inside the profiles array that should change. Omitted fields are left as they are. This is highly useful for automated role changes or correcting email addresses.

"Update profile ID 12345. Change their job_title to 'Senior Account Executive' and set their user_status to 'active'. Leave all other fields unchanged."

Get Single Namely Report by ID

This is one of the most powerful tools in the Namely suite. Reports reflect live data, so each tool call returns current values. Because the payload separates columns and content rows, LLMs excel at ingesting this structural data and summarizing the matrix into human-readable insights.

"Fetch the Headcount and Salary report (ID 884). Look at the columns array to map the data, then tell me the average salary for the Engineering department based on the content matrix."

List All Namely Groups

Groups represent the physical and logical structure of a company (Offices, Departments, Cost Centers). This tool lists groups belonging to a specific group_type, allowing an agent to audit organizational structure.

"Fetch all the groups associated with the 'Office Location' group type, and list their addresses."

Create a Namely Event

Namely includes a social "home feed" for company announcements. This tool creates an announcement event. It is excellent for automating HR communications, such as welcoming new hires or announcing policy changes.

"Post an announcement to the home feed welcoming Jane Doe to the company. Use the text: 'Everyone please welcome Jane Doe, our new Lead Designer, joining us from the Chicago office!'"

List All Namely Resources

Resources are company-wide documents (employee handbooks, policy PDFs, benefit guides). This tool lists resources that are not housed in specific folders, returning their metadata, file format, and file URLs.

"List all company resources available in Namely. Find the document titled '2026 Benefits Guide' and give me the direct file_url so I can download it."

For a complete inventory of available Namely endpoints, query schemas, and body structures, check out the Namely integration page.

Workflows in Action

Providing individual tools is step one. The real power of MCP is giving ChatGPT the context to chain these tools together into autonomous workflows.

Scenario 1: Org Alignment and Reporting Audit

The Persona: An HR Operations Manager auditing reporting structures against live headcount reports.

"Find all active employee profiles that report to 'John Smith'. Then, pull the Q3 Headcount Report (ID 402) and cross-reference those employees to ensure their job titles in the report match their live profile data."

Step-by-step execution:

1. The agent calls list_all_namely_profiles with filter [reports_to]="John Smith" and filter [user_status]="active".
2. The server returns an array of matching employee records.
3. The agent calls get_single_namely_report_by_id with id="402".
4. The server returns the matrix report payload.
5. ChatGPT parses the columns to find the index for "Job Title" and "First Name/Last Name", correlates the two datasets, and outputs a summary of any title discrepancies.

sequenceDiagram
    participant UserPrompt as User Prompt
    participant AI as ChatGPT Agent
    participant MCP as Truto MCP Server
    participant NamelyAPI as Namely API

    UserPrompt->>AI: Find reports for John Smith and cross-reference report 402
    AI->>MCP: call list_all_namely_profiles(filter: {reports_to: "John Smith"})
    MCP->>NamelyAPI: GET /api/v1/profiles?filter[reports_to]=John+Smith
    NamelyAPI-->>MCP: [Profile 1, Profile 2, Profile 3...]
    MCP-->>AI: returns profiles array
    AI->>MCP: call get_single_namely_report_by_id(id: 402)
    MCP->>NamelyAPI: GET /api/v1/reports/402
    NamelyAPI-->>MCP: {columns: [...], content: [[...]]}
    MCP-->>AI: returns report matrix JSON
    AI-->>UserPrompt: Summarizes alignment and highlights 2 discrepancies

Scenario 2: New Hire Onboarding Announcement

The Persona: An Employee Experience Coordinator pushing a scheduled update.

"We just finalized onboarding for Michael Scott. Update his profile (ID 8821) to set his start_date to today. Once that succeeds, publish an announcement event to the home feed welcoming him to the Scranton branch."

Step-by-step execution:

1. The agent calls update_a_namely_profile_by_id passing id="8821" and setting start_date inside the profiles array to today's ISO date.
2. Namely applies the update and returns the modified profile.
3. The agent extracts the confirmation and calls create_a_namely_event to push a formatted string into the content and html_content fields.
4. The agent returns a success message to the user with a link to the new announcement.

flowchart TD
    A["User Prompt: Update Michael Scott and post announcement"] --> B["Agent calls: update_a_namely_profile_by_id<br>(id: 8821, start_date: today)"]
    B --> C{Profile Updated?}
    C -->|Yes| D["Agent calls: create_a_namely_event<br>(content: 'Welcome Michael...')"]
    C -->|No| E["Return error to user"]
    D --> F["Return success confirmation to user"]

Security and Access Control

Exposing an HRIS to an LLM requires strict boundary setting. Truto's MCP architecture provides several layers of access control baked into the token generation layer.

• Method Filtering: When generating the server, set "methods": ["read"] in the configuration payload. Truto will instantly strip all create, update, and delete tools from the resulting schema, making the MCP server structurally incapable of altering Namely data.
• Tag Filtering: You can restrict tool access functionally. Passing "tags": ["profiles", "reports"] ensures the agent cannot discover or access unrelated endpoints like billing or onboarding sessions.
• Time-to-Live (TTL): Passing an expires_at ISO string attaches a strict TTL to the server. Cloudflare KV and internal Durable Objects automatically purge the token at expiration, terminating access even if the client retains the URL.
• Secondary Authentication: By enabling require_api_token_auth, Truto forces the MCP client to pass a valid API token in the Authorization header on top of the unique URL token, preventing unauthorized access if the server URL leaks in a log file.

Handling Rate Limits in Production

Because Truto acts as a pass-through proxy for rate limits, your architecture must be prepared to handle HTTP 429 errors from Namely.

When Namely issues a rate limit block, Truto surfaces the error along with IETF standard HTTP headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset). If you are using a custom agent architecture invoking the MCP server, you must inspect these headers and handle the backoff locally.

// Example: Parsing standardized rate limit headers in a custom MCP client wrapper
async function executeMcpToolWithBackoff(toolName, args, maxRetries = 3) {
  let attempt = 0;
  while (attempt < maxRetries) {
    const response = await mcpClient.post('/mcp/your_token_here', { toolName, args });
    
    if (response.status === 429) {
       const resetTimestamp = parseInt(response.headers['ratelimit-reset'], 10);
       // Calculate wait time or default to 5 seconds
       const waitTime = resetTimestamp ? (resetTimestamp * 1000) - Date.now() : 5000;
       console.warn(`Namely rate limit hit. Backing off for ${waitTime}ms.`);
       
       await new Promise(resolve => setTimeout(resolve, Math.max(waitTime, 1000)));
       attempt++;
       continue;
    }
    
    return response.data;
  }
  throw new Error("Namely rate limit exceeded. Max retries exhausted.");
}

By ensuring your agent respects these normalized headers, you prevent your application from thrashing Namely's API and ensure stable, reliable tool execution.

Powering Agentic HR Workflows

Connecting Namely to ChatGPT via Truto's MCP servers shifts integration from a months-long backend project to an infrastructure configuration task. By relying on documentation-driven tool generation, your AI agents always have access to the most accurate schemas, enabling them to query live organizational data, parse matrix reports, and orchestrate employee lifecycles autonomously.

Instead of wrestling with OAuth handshakes and payload transformations, you can focus on writing better prompts and building more resilient AI workflows.