Skip to content
Truto
Truto Blog
Back
AI & Agents

Connect Unkey to Claude: Automate User Identities and Key Cycles

Learn how to connect Unkey to claude using Truto. Step-by-step guide to tool calling, API quirks, and autonomous workflows.

Uday Gajavalli Uday Gajavalli · · 9 min read
Connect Unkey to Claude: Automate User Identities and Key Cycles

If you need to connect Unkey to Claude to automate API key provisioning, identity management, or rate limiting workflows, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's tool calls and Unkey'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 connecting Unkey to ChatGPT or explore our broader architectural overview on connecting Unkey to AI Agents.

Giving a Large Language Model (LLM) read and write access to your core authentication and rate limiting infrastructure is an engineering challenge. You must handle complex hierarchical data models, map specific JSON schemas to MCP tool definitions, and deal with strict edge-routing latencies. Every time Unkey 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 Unkey, connect it natively to Claude Desktop, and execute complex security workflows using natural language.

The Engineering Reality of the Unkey 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 authentication APIs is painful. You are not just integrating "an API" - you are integrating a highly distributed edge authentication network with very specific design patterns.

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

Eventual Consistency on the Edge Unkey operates as a globally distributed edge network to ensure low-latency key verification. When you create or update an entity - such as setting permissions or roles on a key - those changes can take up to 30 seconds to propagate across all edge regions. If you allow Claude to immediately test a key via the verification endpoint after setting permissions, the LLM will likely receive a stale response, assume the tool failed, and attempt to run the command again. A properly mapped MCP tool set requires precise contextual instructions so the model understands this propagation delay.

The Quirks of Verification Endpoints Unkey's verification endpoints do not behave like standard CRUD endpoints. For example, the unkey_keys_verify endpoint almost always returns an HTTP 200 OK, even if the key is invalid, expired, or rate-limited. The actual authorization state is buried in a boolean valid field inside the response payload. Unprompted, Claude will often see the HTTP 200 and mistakenly tell the user "The key is fully valid and working." Truto's auto-generated schemas handle this by explicitly structuring the tool descriptions so the model knows to inspect the valid boolean and its associated metadata.

Rate Limit Passthrough and Header Normalization When you are programmatically generating API keys and identities via LLM, you can easily hit Unkey's management API rate limits. It is critical to understand how Truto handles this: Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream Unkey API returns an HTTP 429 Too Many Requests, Truto passes that error directly to the caller. However, Truto normalizes Unkey's specific rate limit info into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. The caller (the AI agent framework) is completely responsible for handling the retry and backoff logic using these normalized headers.

Instead of dealing with this boilerplate, you can use Truto to derive tool definitions directly from Unkey's endpoint schemas, turning every feature into an AI-ready capability.

How to Generate an Unkey MCP Server with Truto

Truto dynamically generates MCP tools from an integration's documentation and resource configurations. There are two ways to generate your Unkey MCP server.

Method 1: Via the Truto UI

For teams who prefer a visual setup flow, you can generate the server directly from the dashboard.

  1. Navigate to the integrated account page for your Unkey connection.
  2. Click the MCP Servers tab.
  3. Click Create MCP Server.
  4. Select your desired configuration. You can apply tag filters, restrict allowed methods (like read only), and set an optional expiration date.
  5. Click Save and copy the generated MCP server URL (e.g., https://api.truto.one/mcp/abc123xyz...).

Method 2: Via the API

For platform engineers building multi-tenant AI products, you can provision Unkey MCP servers programmatically. Make a POST request to /integrated-account/:id/mcp.

curl -X POST https://api.truto.one/admin/integrated-accounts/YOUR_ACCOUNT_ID/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Unkey Automation Agent",
    "config": {
      "methods": ["read", "write", "custom"],
      "require_api_token_auth": false
    }
  }'

The API provisions a secure token and returns the full url required by Claude.

Connecting the Unkey MCP Server to Claude

Once you have your Truto MCP server URL, you must register it with Claude. There are two supported methods depending on your environment.

Method 1: Via the Claude UI

If you are using the consumer-facing Claude Desktop or a managed enterprise workspace, you can add the server via the visual interface.

  1. Open Claude and navigate to Settings.
  2. Select Integrations (or Connectors depending on your tier).
  3. Click Add MCP Server.
  4. Paste the Truto MCP URL.
  5. Click Add. Claude will instantly execute a handshake, pull down the Unkey tool schemas, and make them available for the session.

Method 2: Via Manual Configuration File

For developers orchestrating Claude Desktop locally or managing configuration via code, you can use the claude_desktop_config.json file. This leverages the official Server-Sent Events (SSE) transport adapter.

Modify your config file (typically located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows):

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

Restart Claude Desktop. The model will automatically read this configuration and establish a persistent connection to the Unkey API.

Unkey Hero Tools for Claude

Truto exposes the entirety of the Unkey REST API. Here are the highest-leverage tools available to your LLM for automating authentication lifecycles.

create_a_unkey_api

Creates a new API namespace in Unkey. A namespace is the top-level container for all keys and identities for a specific service or application.

Usage note: This is typically step one of an automated tenant provisioning pipeline. You must provide a name.

"I need to spin up a new authentication namespace for the staging environment. Call it 'Staging API 2026'. Please create the Unkey API namespace and return the apiId."

create_a_unkey_identity

Creates an identity to group API keys under a single entity. Identities allow you to share metadata and rate limits across multiple keys owned by the same user or organization.

Usage note: Identities should be linked to your internal system's UUID via the externalId field.

"We just onboarded a new enterprise customer with tenant ID 'org_98765'. Create a new Unkey identity using that external ID so we can group all of their upcoming keys under one umbrella."

create_a_unkey_key

Generates a new Unkey API key within a specified API namespace. The plaintext key is only returned once in the response payload.

Usage note: Because the plaintext key is never retrievable again, your AI agent must be instructed to pass this value immediately to your secure storage or return it safely to the developer.

"Generate a new API key for the 'Staging API 2026' namespace we just created. Ensure you capture the plaintext key from the response and display it to me in a secure code block."

unkey_keys_set_permissions

Replaces all direct permissions on an Unkey key in one atomic operation. This dictates exactly what the key is allowed to do in your system.

Usage note: Remember the edge propagation delay. Changes made with this tool may take up to 30 seconds to distribute across Unkey's global network.

"Take the key ID 'key_abc123' and set its permissions to strictly 'read_reports' and 'write_metrics'. Remove any other permissions it currently holds."

unkey_keys_verify

Verifies an Unkey API key's validity, permissions, rate limits, and usage quota. This mimics exactly how your backend services check keys at runtime.

Usage note: As mentioned earlier, this tool always returns HTTP 200. The LLM must read the valid field inside the data object.

"I need to test if the plaintext key 'unkey_xzy890...' is actually working. Run a verification check and tell me if the 'valid' flag is true, and list out the remaining credits."

unkey_keys_reroll

Generates a new Unkey API key while preserving an existing key's exact configuration, permissions, and identity mappings.

Usage note: This is critical for security incident response. You can reroll a compromised key without breaking the underlying application logic, while setting the old key to expire gracefully.

"A developer accidentally committed key 'key_def456' to GitHub. Reroll this key immediately to generate a new plaintext value, and set the compromised key to expire in exactly 2 hours."

For the complete inventory of tools, schemas, and parameter details, visit the Unkey integration page.

Workflows in Action

When you connect Unkey to Claude, you graduate from manual dashboard clicks to autonomous, multi-step execution. Here are two real-world workflows that demonstrate this power.

Scenario 1: Provisioning a New Developer Sandbox

When onboarding a new partner, IT admins need to create a dedicated identity, provision an API key, and assign strict sandbox permissions.

User Prompt:

"A new partner (external ID: 'partner_acme_01') needs a sandbox environment. Create an identity for them. Then, generate a new API key in the 'Sandbox API' namespace and assign it only the 'sandbox_read' permission. Show me the final plaintext key."

How Claude executes this:

  1. Calls create_a_unkey_identity passing externalId: "partner_acme_01". Extracts the new identity ID.
  2. Calls create_a_unkey_key passing the API namespace ID and the newly created identity ID. Captures the keyId and the plaintext key.
  3. Calls unkey_keys_set_permissions using the keyId to assign the sandbox_read string.

The Result: Claude completes the entire provisioning chain in seconds, returning the plaintext key to the user and confirming that the permissions will be fully active on the edge network within 30 seconds.

sequenceDiagram
    participant User as User
    participant Claude as Claude Desktop
    participant Truto as Truto MCP Server
    participant Unkey as Unkey API

    User->>Claude: "Provision sandbox for partner_acme_01"
    Claude->>Truto: call create_a_unkey_identity
    Truto->>Unkey: POST /v1/identities.createAPI
    Unkey-->>Truto: identity_id: id_890
    Truto-->>Claude: identity_id: id_890
    
    Claude->>Truto: call create_a_unkey_key (apiId, identityId)
    Truto->>Unkey: POST /v1/keys.createKey
    Unkey-->>Truto: keyId: key_123, plaintext: unkey_abc...
    Truto-->>Claude: keyId: key_123, plaintext: unkey_abc...
    
    Claude->>Truto: call unkey_keys_set_permissions (key_123, ["sandbox_read"])
    Truto->>Unkey: POST /v1/keys.setPermissions
    Unkey-->>Truto: Success
    Truto-->>Claude: Success
    Claude-->>User: "Sandbox provisioned. Plaintext key: unkey_abc..."

Scenario 2: Emergency Key Remediation

When a potential security breach occurs, security teams need to rapidly rotate keys without causing hard downtime for the application.

User Prompt:

"We received a security alert for key ID 'key_alpha_99'. I need you to immediately reroll this key. Set the old key to expire in 60 minutes to give the team time to swap it. Then, verify the newly generated plaintext key to ensure it inherited the correct permissions."

How Claude executes this:

  1. Calls unkey_keys_reroll passing keyId: "key_alpha_99" and calculating the expiration timestamp for 60 minutes in the future.
  2. Extracts the new keyId and new plaintext key from the response.
  3. Calls unkey_keys_verify using the new plaintext key.
  4. Reads the valid field and the permissions array from the verification response to ensure the inherited state is correct.

The Result: Claude securely rotates the credential, applies a grace period to prevent production outages, and runs an automated integration test on the new key - all from a single natural language command.

Security and Access Control

Exposing authentication infrastructure to an LLM introduces obvious risks. Truto provides four distinct layers of security to scope and protect your Unkey MCP servers:

  • Method Filtering: Restrict an MCP server to only perform specific operations. For an auditing agent, you can configure methods: ["read"] to allow get and list operations while strictly blocking create, update, or delete.
  • Tag Filtering: Limit the server's scope to specific functional areas. By filtering on specific tags, you can expose only identity-related tools without exposing key generation tools.
  • API Token Authentication: By default, anyone with the MCP server URL can connect. By setting require_api_token_auth: true, Truto forces the connecting client to provide a valid Truto API token in the Authorization header, adding a secondary layer of enterprise identity verification.
  • Automatic Expiration: For temporary elevated access (e.g., granting an agent permissions during an active incident response), you can set the expires_at field. Truto automatically schedules a cleanup process that destroys the token and revokes access at the exact millisecond requested.

Moving Faster with Managed Infrastructure

Connecting Unkey to Claude manually means writing boilerplate JSON-RPC handlers, mapping complex hierarchical authentication schemas, and normalizing specific rate limit headers. It is a massive tax on engineering teams who should be focused on product features.

By using Truto, you bypass the infrastructure build entirely. Truto derives the tool capabilities dynamically from Unkey's documentation, handles the protocol routing, and exposes a secure URL that connects directly to Claude.

More from our Blog