Connect Herd Security to Claude: Audit User Status and Tagging

If you need to connect Herd Security to Claude to audit user training statuses, manage tags, or automate compliance reporting, you need a Model Context Protocol (MCP) server. This server acts as a translation layer between Claude's function calling capabilities and Herd Security's REST API. You can either build, host, and maintain this infrastructure yourself, or use a managed MCP server via a platform like Truto to dynamically generate a secure, authenticated URL. If your team uses ChatGPT, check out our guide on connecting Herd Security to ChatGPT or explore our broader architectural overview on connecting Herd Security to AI Agents.

Giving a Large Language Model (LLM) read and write access to a security awareness platform like Herd Security requires precise engineering. You have to handle API authentication lifecycles, map relational data structures (users, tags, trainings, and enrollments) to flat MCP tool schemas, and safely handle strict rate limits. Every time the vendor updates an endpoint, 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 Herd Security, connect it natively to Claude Desktop or Claude Web, and execute complex compliance workflows using natural language.

The Engineering Reality of the Herd Security API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable JSON-RPC 2.0 interface for models to discover tools, the reality of implementing it against Herd Security's APIs is complex.

If you decide to build a custom MCP server for Herd Security, you own the entire API lifecycle. Here are the specific challenges you will face:

Temporal Tag Management and Relational Joins Herd Security relies heavily on temporal tagging. Tags are not just static labels applied to users - they have a start_date and end_date, dictating when specific training campaigns are active. To answer a simple prompt like "Who missed the Q3 Phishing training?", an LLM needs to resolve the tag, map that tag to specific trainings, and then query the enrollment status for those trainings across the user directory. Exposing raw API endpoints directly to Claude often results in the model getting lost in relational joins. A properly designed MCP server must expose these relationships cleanly via distinct, well-documented tools.

Directory Pagination Models Security awareness platforms deal with massive user directories. When an LLM requests a list of all enrollments to audit completion statuses, it cannot pull 10,000 records into context at once. You must implement robust pagination. If you expose raw, unstandardized pagination parameters to Claude, the model will frequently hallucinate cursor values or misunderstand how to iterate through pages. Truto normalizes this across all endpoints into a standard limit and next_cursor schema, explicitly instructing the LLM to pass cursor values back unchanged.

Aggressive Rate Limiting on Bulk Reads Herd Security enforces strict rate limits on directory reads and enrollment queries to protect platform stability. If an AI agent attempts to iterate through 50 pages of enrollments too quickly, the API will reject the requests. You must ensure your MCP server properly surfaces these rate limit signals to the LLM so it can handle backoff and retry logic, rather than failing silently.

How to Generate a Managed MCP Server for Herd Security

Truto's MCP architecture turns any connected integration into a dynamic tool server. Rather than writing custom integration code, Truto derives tool definitions from the integration's underlying schema and documentation records. A tool only appears in the MCP server if it has a corresponding documentation entry - acting as a quality gate to ensure only well-described endpoints are exposed to the LLM.

Each MCP server is scoped to a single integrated account. The server URL contains a cryptographic token that encodes the account credentials, tool filters, and expiration data.

You can create this server in two ways.

Method 1: Via the Truto UI

If you prefer a visual interface, you can generate an MCP server directly from the Truto dashboard:

1. Navigate to the Integrated Accounts page for your connected Herd Security instance.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Select your desired configuration (name, allowed methods like read or write, specific tags, and expiration limits).
5. Copy the generated MCP server URL (e.g., https://api.truto.one/mcp/a1b2c3d4...).

Method 2: Via the REST API

For teams embedding this functionality into their own applications, you can generate MCP servers programmatically.

The Truto API validates that the Herd Security integration has documented tools available, generates a secure random hex string, hashes it with an HMAC signing key, stores it in Cloudflare KV for high-speed edge lookups, and returns a ready-to-use URL.

Make a POST request to /integrated-account/:id/mcp:

curl -X POST https://api.truto.one/integrated-account/<integrated_account_id>/mcp \
  -H "Authorization: Bearer <your_truto_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Herd Security Compliance Audit Server",
    "config": {
      "methods": ["read"]
    }
  }'

The response will contain the authenticated URL you need to configure Claude:

{
  "id": "mcp_123456789",
  "name": "Herd Security Compliance Audit Server",
  "config": {
    "methods": ["read"]
  },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f67890"
}

How to Connect the MCP Server to Claude

Once you have the Truto MCP URL, you can connect it to Claude. When Claude initializes the connection, it sends an initialize JSON-RPC request. The Truto router validates the hashed token at the edge, verifies the underlying Herd Security API credentials, and returns a dynamic list of capabilities and available tools.

You can connect the server in two ways, depending on which version of Claude you use.

Method A: Via the Claude UI (Claude for Work)

If you are using Claude's web interface on a paid tier that supports custom integrations:

1. In Claude, navigate to Settings -> Integrations.
2. Click Add MCP Server or Add custom connector.
3. Give the server a descriptive name (e.g., "Herd Security").
4. Paste the Truto MCP URL provided in the previous step.
5. Click Add. Claude will perform the handshake and instantly discover the Herd Security tools.

Method B: Via Manual Config File (Claude Desktop)

If you are running Claude Desktop locally for development or local workflows, you must modify your claude_desktop_config.json file. Truto provides an SSE (Server-Sent Events) bridge command via the official MCP SDK to translate the remote URL into a local standard input/output process.

Update your config file (typically located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

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

Restart Claude Desktop. The application will execute the npx command, connect to the Truto edge router, and load the Herd Security tools into the UI.

Security and Access Control

Exposing a security awareness platform to an AI model requires strict governance. Truto MCP servers support multiple layers of access control, designed for zero-data retention and SOC 2 compliance, enforced at the router level before any request reaches the proxy API:

• Method Filtering: Use config.methods to restrict the server to read operations (get, list). This prevents the LLM from accidentally mutating user data or altering tag schemas.
• Tag Filtering: Use config.tags to limit the server to specific resource subsets. If your integration is tagged by domain, you can scope the server to only expose users and enrollments, hiding sensitive administrative resources.
• API Token Authentication: Setting require_api_token_auth: true forces the client to pass a valid Truto API token in the Authorization header, adding a secondary identity check beyond the tokenized URL.
• Time-to-Live (TTL): Set expires_at with an ISO datetime string to create ephemeral access. Truto automatically schedules a Durable Object alarm to purge the token and its associated edge KV entries the millisecond it expires.

Herd Security Hero Tools for Claude

Truto automatically generates descriptive, snake_case tool names from the Herd Security integration schema. Query parameters and body schemas are flattened into a single input namespace, allowing Claude to cleanly map natural language to the required API arguments.

Here are the core hero tools available for Herd Security workflows.

list_all_herd_security_users

Fetches a paginated list of users enrolled in your Herd Security organization. This is the foundation for any compliance audit. It returns user IDs, names, emails, and overarching platform statuses.

Usage note: Because directories can be large, Claude is instructed via the schema description to utilize the limit and next_cursor fields for pagination if it needs to process the entire organization.

"Pull a list of all active users in our Herd Security directory, fetching 100 records at a time. Compile a list of anyone whose status is flagged as inactive."

get_single_herd_security_user_by_id

Retrieves the detailed record for a specific user based on their unique identifier.

Usage note: Truto automatically injects the id requirement into the query schema. This tool is typically called by Claude after discovering a specific user via the list operation, allowing for deep dives into an individual's security posture.

"Get the detailed user profile for user ID 8a7b6c5d. I need to verify their email address and exact activation date."

list_all_herd_security_tags

Returns the list of tags used to categorize training cohorts and compliance campaigns. Tags contain crucial temporal data (start_date, end_date) that dictate active requirements.

Usage note: This is critical for understanding which training requirements apply to which timeframes. Claude uses this to figure out the ID of a specific campaign before checking user enrollments.

"List all active tags in Herd Security. Find the tag ID that corresponds to the '2024 Q3 Phishing Awareness' campaign."

get_single_herd_security_tag_by_id

Fetches the configuration details of a single tag, including its temporal boundaries and specific metadata.

Usage note: Used to verify the specific start and end dates of a compliance requirement if the list endpoint does not return the full configuration schema.

"Retrieve the details for tag ID 12345. Tell me exactly when this tag expires."

list_all_herd_security_tag_trainings

Lists all specific training modules associated with a given tag in Herd Security. This bridges the gap between a campaign (tag) and the actual courses users must complete.

Usage note: Requires the tag_id. Claude will first look up the tag, then call this tool to see exactly which courses comprise the requirement.

"Look up all the trainings associated with tag ID 12345. Give me the titles and descriptions of the mandatory courses."

list_all_herd_security_enrollments

Retrieves training enrollments and their completion statuses. This tool joins user context with training requirements, returning fields like enrollment_date, completion_date, and the final status.

Usage note: This is the highest-leverage endpoint for compliance reporting. Claude can use it to cross-reference users who have not completed mandatory modules.

"List all enrollments for training ID 98765. Filter the results to show me only the users whose status is not marked as completed."

Workflows in Action

Connecting Herd Security to Claude via MCP allows you to string multiple tool calls together to solve complex, multi-step compliance problems. Here are two real-world examples of how an AI agent navigates the API.

Workflow 1: Auditing Mandatory Training Delinquency

IT administrators spend hours cross-referencing user directories against course completions. Claude can automate this entirely.

"Find the tag for 'Annual Security Compliance 2024'. Get the trainings associated with it, and then give me a list of all user emails who have an incomplete enrollment status for those trainings."

Step-by-step execution:

1. Claude calls list_all_herd_security_tags to search for the string "Annual Security Compliance 2024" and extracts the tag_id.
2. Claude calls list_all_herd_security_tag_trainings using the extracted tag_id to retrieve the associated training_ids.
3. Claude calls list_all_herd_security_enrollments for the identified training IDs, analyzing the status field for incomplete records.
4. Claude calls get_single_herd_security_user_by_id for the delinquent user_ids to fetch their email addresses and formats the final report.

Workflow 2: Investigating Campaign Configurations

When a new employee complains they cannot see a required course, compliance officers need to audit the campaign configuration.

"Check if the tag for 'New Hire Phishing 101' is currently active based on its start and end dates. If it is active, verify which specific trainings are attached to it."

Step-by-step execution:

1. Claude calls list_all_herd_security_tags to find the "New Hire Phishing 101" campaign.
2. Claude inspects the returned start_date and end_date against the current date to determine if the campaign is active.
3. Claude calls list_all_herd_security_tag_trainings using the campaign's tag_id to list the actual course titles attached to the cohort, reporting the findings back to the user.

Handling Pagination and Rate Limits

When building agentic workflows, handling edge cases like pagination and rate limiting is critical. Truto normalizes these constraints at the proxy API layer, but understanding how they surface to Claude is essential for reliable automation.

Normalized Pagination Instead of exposing Herd Security's native pagination quirks, Truto injects limit and next_cursor properties into the query_schema during tool generation. The next_cursor description explicitly instructs the LLM: "Always send back exactly the cursor value you received... without decoding, modifying, or parsing it." This prevents Claude from hallucinating offset integers or guessing token formats.

Factual Rate Limit Behavior Herd Security limits how many requests you can make in a given window. Truto does not retry, throttle, or apply backoff on rate limit errors. If the upstream Herd Security API returns an HTTP 429 Too Many Requests, Truto immediately passes that error back to Claude.

However, Truto normalizes the upstream rate limit information into standard IETF headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset). This provides Claude with the exact context it needs to pause its execution loop and retry the tool call once the window resets.

sequenceDiagram
    participant Claude as Claude Desktop
    participant MCP as Truto MCP Server
    participant Upstream as Upstream API (Herd Security)

    Claude->>MCP: tools/call (list_all_herd_security_enrollments)<br>with limit=100
    MCP->>Upstream: GET /api/v1/enrollments
    Upstream-->>MCP: HTTP 429 Too Many Requests
    MCP-->>Claude: Error: 429 (ratelimit-reset: 60)
    Note over Claude: Claude reads standard headers<br>and schedules a retry

Automating Compliance with Truto

Connecting Herd Security to Claude via MCP transforms static compliance dashboards into interactive, natural-language auditing engines. Instead of manually exporting CSVs and running VLOOKUPs to match users with incomplete trainings, your team can simply ask Claude to identify delinquencies and summarize campaign statuses.

By leveraging Truto to generate the MCP server, you bypass the friction of managing OAuth lifecycles, maintaining temporal data schemas, and normalizing API errors. You get immediate, secure tool calling out of the box.

Stop writing boilerplate integration code. Let Truto handle the connectivity layer so your engineering team can focus on building intelligent, agent-driven features.