Connect Kisi to Claude: Manage Users, Teams & Device Configs

If you need to connect Kisi to Claude to automate user provisioning, trigger office lockdowns, manage card assignments, or audit access logs, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's natural language tool calls and Kisi's physical security 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-kisi-to-chatgpt-automate-access-security-monitoring/ or explore our broader architectural overview on /connect-kisi-to-ai-agents-orchestrate-smart-facility-operations/.

Giving a Large Language Model (LLM) read and write access to physical infrastructure like Kisi is an engineering challenge with high stakes. You have to handle API token lifecycles, map complex JSON schemas to MCP tool definitions, and deal with physical hardware latency. Every time Kisi updates an endpoint or deprecates a legacy card resource, 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 Kisi, connect it natively to Claude Desktop, and execute complex physical security workflows using natural language.

The Engineering Reality of the Kisi 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 specialized physical security APIs is painful. Kisi is built to manage physical locks, localized controllers, and complex organizational hierarchies. Its API reflects that physical reality.

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

Asynchronous Hardware States and Latency Unlike a typical B2B SaaS API where a database update is instantaneous, Kisi interacts with physical IoT devices. When you call an endpoint like POST /locks/{id}/unlock, the API returns a success response to indicate that the command was successfully dispatched to the local controller. It does not guarantee that the physical lock mechanism actually fired. Your MCP server must be designed so that the LLM understands this distinction - returning "Unlock command sent successfully" rather than an absolute "The door is open."

Ephemeral Event Streams and Cursor Pagination Querying historical access logs in Kisi is not a matter of a simple limit/offset REST call. Kisi uses a unique pattern where you must first create an "Event Set" (POST /event_sets) representing your filtered query. This returns a temporary resource that lives for approximately 24 hours, along with a cursor. You must then poll that specific event set ID to paginate through the results. Instructing an LLM to orchestrate this two-step temporary resource pattern natively is nearly impossible without a strictly typed middleware layer to abstract the pagination logic.

Polymorphic Access Control Records Kisi's Role-Based Access Control (RBAC) relies heavily on polymorphic associations. A RoleAssignment might apply to an Organization, a Place, or a specific Group. The applies_to_type and assignee_type fields drastically change the shape of the required payload. If an LLM is guessing the schema based on a generic description, it will frequently trigger HTTP 422 Unprocessable Entity errors. Managed MCP tools explicitly define the required permutations in the JSON schema, preventing hallucinations.

Factual Note on Rate Limits Truto does not retry, throttle, or apply backoff on rate limit errors. When an upstream API like Kisi returns an HTTP 429 Too Many Requests, Truto passes that error directly to the caller. Truto normalizes upstream rate limit info into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF spec. The client (your AI agent framework or Claude Desktop client) is responsible for executing retry and backoff logic.

How to Create the Kisi MCP Server

Truto dynamically generates MCP tools based on the resources available in your connected Kisi account. The tool generation is documentation-driven, ensuring Claude only sees curated, AI-ready operations with explicitly defined JSON schemas.

There are two ways to generate your secure MCP server URL.

Method 1: Via the Truto UI

The fastest way to spin up an MCP server for a connected Kisi instance is directly through the Truto dashboard.

1. Navigate to the Integrated Accounts page in your Truto dashboard.
2. Select your connected Kisi account.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Select your desired configuration (e.g., read-only tools, specific resource tags, or an expiration date).
6. Copy the generated MCP server URL. (It will look like https://api.truto.one/mcp/abc123def456...).

Method 2: Via the Truto API

For platform engineers building multi-tenant AI products, you can generate MCP servers programmatically. This is ideal if you want to provision dedicated MCP servers for each of your customers' individual Kisi instances.

Make an authenticated POST request to the Truto API:

curl -X POST https://api.truto.one/integrated-account/{kisi_integrated_account_id}/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Kisi Security Operations",
    "config": {
      "methods": ["read", "write"],
      "tags": ["directory", "access_control"]
    },
    "expires_at": "2026-12-31T23:59:59Z"
  }'

The API returns a payload containing the secure URL. Truto handles the token generation, securely hashes it, and stores it in edge KV storage for low-latency authentication during protocol handshakes.

{
  "id": "mcp_01hq...",
  "name": "Kisi Security Operations",
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f67890",
  "expires_at": "2026-12-31T23:59:59Z"
}

Connecting the MCP Server to Claude

Once you have your Truto MCP URL, you can plug it into your LLM interface of choice. Claude discovers the tools dynamically during the JSON-RPC initialization handshake.

Method A: Via the Claude UI (Or ChatGPT)

If you are using an AI client that supports UI-based MCP configuration (like ChatGPT Developer Mode or Claude Web if enabled):

1. In your client, navigate to Settings -> Connectors (or Integrations).
2. Click Add Custom Connector or Add MCP Server.
3. Paste the Truto MCP URL into the Server URL field.
4. Click Save or Add.

The client will immediately ping the endpoint, execute the tools/list command, and register the Kisi tools for use.

Method B: Via Manual Configuration File (Claude Desktop)

If you are using Claude Desktop, you configure remote MCP servers via the claude_desktop_config.json file. Because Truto provides a remote HTTP endpoint, we use the standard Model Context Protocol SSE transport wrapper to bridge the local Claude instance to the remote API.

Open your configuration file (located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows) and add the following:

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

Restart Claude Desktop. You will now see a "hammer" icon indicating that the Kisi tools have been successfully loaded.

Kisi Hero Tools for Claude

Truto automatically translates the Kisi API into descriptive, snake_case tools. Here are the most critical operations for facility management and access control.

list_all_kisi_locks

Fetches a comprehensive inventory of all locks across your places. This tool supports complex filtering, allowing Claude to find locks by floor, online status, or lockdown state.

Usage Note: This is often the first tool an agent should use to resolve a plain-text location name (e.g., "the front door") to a specific lock_id required for action commands.

"List all locks in the New York office (place_id 9876) that are currently marked as offline or disabled."

kisi_locks_unlock

Triggers a remote unlock command for a specific lock.

Usage Note: The LLM must provide the lock_id. The response is typically a fast 204 No Content indicating the dispatch was successful. It does not mean the door was physically pushed open.

"Unlock the Main Entrance lock (lock_id 12345) immediately to let the delivery driver in."

create_a_kisi_user

Provisions a new user in the Kisi directory.

Usage Note: This tool requires basic identity information (name, email). By default, this only creates the identity record. To grant actual physical access, the agent must subsequently call create_a_kisi_group_link or create_a_kisi_role_assignment.

"Create a new Kisi user profile for Alice Smith (alice@example.com). Make sure access_enabled is set to true."

list_all_kisi_groups

Retrieves the access groups defined in the organization. Groups are the primary mechanism for bundling multiple locks into a single assignable entity.

Usage Note: Use this to look up a group_id before attempting to assign a new employee to an access tier.

"Find the group ID for the 'Engineering Access - Floor 4' group so I can assign a new hire to it."

create_a_kisi_card_assignment

Links a physical credential (like an RFID card) or a digital token to a user or guest.

Usage Note: The LLM must pass a card_assignment object containing the assignee_type (usually "User"), the assignee_id, and the card_id.

"Assign card ID 887766 to user ID 5544 as their primary credential."

create_a_kisi_place_lock_down

Initiates a facility-wide lockdown. This overrides all schedules and normal access logic, locking all doors associated with the specified place.

Usage Note: This is a high-consequence action. The only required parameter is the place_id. You should ensure strict method filtering is in place before exposing this tool to an autonomous agent.

"Initiate an emergency lockdown for the London facility (place_id 3321)."

To view the complete inventory of available Kisi tools - including operations for elevator stops, wireless locks, camera integrations, and compliance reporting - visit the Kisi integration page.

Workflows in Action

When Claude has access to these tools, it can orchestrate complex, multi-step physical security workflows simply by reasoning through the required API steps.

Scenario 1: Automated Employee Onboarding

When a new employee joins, IT needs to create their profile, assign them to the correct security group, and issue a mobile credential.

"We have a new engineering hire starting today. Her name is Sarah Connor (sarah@cyberdyne.com). Create her Kisi profile, find the 'Server Room Access' group, and assign her to it so she can get in."

How the agent executes this:

1. Calls create_a_kisi_user passing Sarah's name and email. The tool returns the new user_id.
2. Calls list_all_kisi_groups using a freetext query for "Server Room Access". It parses the response to find the correct group_id.
3. Calls create_a_kisi_role_assignment (or create_a_kisi_group_link depending on organizational structure) mapping the new user_id to the group_id.
4. Returns a summary to the IT admin confirming the access rights have been provisioned.

sequenceDiagram
  participant User as IT Admin
  participant Claude as Claude
  participant MCP as Truto MCP Server
  participant Kisi as Kisi API
  
  User->>Claude: "Onboard Sarah Connor (sarah@...) to Server Room Access."
  Claude->>MCP: Call create_a_kisi_user
  MCP->>Kisi: POST /users
  Kisi-->>MCP: Returns user_id (8899)
  MCP-->>Claude: Tool result (user_id 8899)
  Claude->>MCP: Call list_all_kisi_groups
  MCP->>Kisi: GET /groups?query=Server
  Kisi-->>MCP: Returns group_id (1122)
  MCP-->>Claude: Tool result (group_id 1122)
  Claude->>MCP: Call create_a_kisi_group_link
  MCP->>Kisi: POST /group_links (user 8899, group 1122)
  Kisi-->>MCP: 200 OK
  MCP-->>Claude: Success
  Claude-->>User: "Sarah is provisioned for Server Room Access."

Scenario 2: Emergency Lockdown and Verification

During a physical security incident, an operator needs to lock down a site and verify who was recently on the premises.

"Lock down the Austin office immediately. Once it's locked down, pull the presence logs to tell me who accessed the building in the last 2 hours."

How the agent executes this:

1. Calls list_all_kisi_places to resolve "Austin office" to a specific place_id.
2. Calls create_a_kisi_place_lock_down passing the resolved place_id. It confirms the 204 success response.
3. Calls list_all_kisi_presences for that place_id with the current date to fetch the daily access logs.
4. Analyzes the last_unlock_at timestamps in the payload, filtering for events within the last two hours, and presents a summarized list of personnel to the security operator.

Security and Access Control

Exposing physical access control APIs to LLMs requires strict governance. Truto MCP servers provide several layers of security to limit the blast radius of an AI agent.

• Method Filtering: Configure the MCP token with config.methods: ["read"] to strictly prevent the LLM from unlocking doors or changing permissions. The MCP router enforces this at the protocol level, completely hiding write operations during the tools/list initialization.
• Tag Filtering: Use config.tags to limit the agent's scope to specific domains. For example, filtering by ["directory"] allows the agent to manage users and groups but prevents it from interacting with hardware locks or elevator relays.
• Extra Authentication: Enable require_api_token_auth to force the client to pass a valid Truto API token in the Authorization header. This ensures that mere possession of the MCP URL is not enough to execute tools - the caller must also be an authenticated member of your team.
• Time-to-Live (TTL): Set an expires_at timestamp when generating the server. Once the timestamp is reached, a Durable Object alarm automatically wipes the credentials from the edge KV store, instantly revoking the AI's access to the facility.

Moving Forward with AI Facility Management

Connecting Kisi to Claude transforms physical security from a click-heavy dashboard exercise into a natural language dialogue. By utilizing a managed MCP server, your team bypasses the complexities of hardware latency abstractions, polymorphic JSON mapping, and authentication lifecycles. Instead of building integration infrastructure, your engineering team can focus on deploying intelligent, context-aware agents that can securely orchestrate user provisioning, manage compliance audits, and react to facility events in real time.