Integrating with Kira: Technical Guide

How to read this doc. Every platform mechanism described here (MCP tool groups, the MCP gateway endpoint, the tenant and permission model, ingress webhooks, the OAuth client-credentials helper, per-tenant connection storage) is implemented and shipped in the Kira platform today. Per-partner instantiations (the connector, the tool list, the external API calls) are marked Partner onboarding and specified against the shipped reference implementation: an EHR connector that is code-complete in the Kira platform and the template to clone. The worked examples in Section 9 apply this platform to specific systems of record; the platform mechanics are identical for any external system.

---

0. Reviewer's guide

Related doc set:

1. This guide: auth, the MCP tool-group mechanism, the connector pattern, data-model mapping, ingress webhooks, the partner checklist, and the phasing template.
2. API reference: POST /mcp, the per-partner inbound webhook pattern, error shapes, and auth headers. See the API Reference tab.
3. Worked examples: see Section 9. Partner-specific walk-throughs are delivered during onboarding by your Rezonate integration representative.

Decisions that apply to all connectors:

1. Permission slugs. Use integration:view / integration:manage. The reference connector's MCP tools use these same slugs; they are the shipped precedent in the tool permission registry. Add dedicated <partner>:* slugs only if tenant-level isolation is later required.
2. Connection storage. Store connection config on the Kira side (Kira calls the external API directly; recommended), or as a per-tenant MCP-server installation (only if the partner hosts its own MCP server). See Section 3.3.
3. Write ordering. Always prove auth and read-only before enabling write-back. See Section 7.

---

1. Overview

Kira is the system of engagement and orchestration. Any external system, such as an EHR, CRM, ERP, ticketing platform, or membership database, that holds records the agent needs to read or write is a system of record integrated through Kira's MCP tool-group mechanism.

Two integration directions:

Direction	What moves	Transport	Trigger
Kira → external system (primary)	Read and/or write data via the external system's API	Outbound HTTPS from the Kira control plane, authenticated with a partner-issued token	An agent invokes a <partner>_* MCP tool mid-conversation
External system → Kira (optional, later phase)	Partner notifies Kira of an event (record lapsed, status changed, etc.)	Inbound HTTPS POST to a Kira ingress webhook, authenticated with a shared ingress secret	A webhook, plug-in, or automation flow in the external system calls Kira

This is a proxy-first integration, not a bulk sync. Kira does not replicate the external system's database. Each agent turn makes a minimum-necessary, permission-gated call against the live external system and (optionally) writes a single record back. Durable Kira-side state is limited to the connection config, the tool-invocation audit ledger, and any canonical Person/TimelineEvent rows the tenant chooses to persist.

Architecture

---

2. Authentication

2.1 Kira → external system (server-to-server, client credentials)

For external systems that support OAuth 2.0 client-credentials grants, Kira has a generic token helper. It accepts any token endpoint, scope, client ID, and client secret, and is reused by the reference connector today (see Section 3.2).

The helper:

• assembles the x-www-form-urlencoded body,
• forwards an optional scope,
• follows region redirects,
• enforces a 10-second timeout,
• throws on non-2xx or a missing access_token.

The reference connector wires this helper end-to-end today, including a token cache keyed by apiBase|clientId with a 30-second expiry skew. Any new connector clones this pattern: same helper, partner-specific token endpoint and scope, per-instance token cache with forced refresh on 401.

For external systems that use other auth patterns (API key, OAuth 2.0 with a stored refresh token, etc.), the connector adapts accordingly: the rest of the platform mechanics (MCP gateway, permission gating, audit ledger, egress safety gate) are identical.

Every outbound token/API URL is SSRF-validated before the fetch, exactly as the reference connector does. The partner's API host and auth token endpoint must both pass that gate.

2.2 Inbound caller auth to the MCP gateway

The agent reaches a tool group through Kira's MCP gateway, which is OAuth-protected and tenant-scoped:

• Endpoint: POST /mcp.
• The endpoint resolves a Kira-issued bearer → tenant identifier → Kira tenant, and returns a 401 with WWW-Authenticate when the token is missing or invalid.
• Inside each tool, permission validation resolves the caller's canonical user, looks up their membership role in the tenant, and asserts the tool's permission slug. No membership or a missing permission returns a permission error.

Partner engineers generally do not call /mcp directly in production; the agent runtime does, on behalf of an authenticated tenant. A partner's responsibility is the external API side (Section 2.1) plus, optionally, the inbound webhook (Section 5).

---

3. The MCP tool-group mechanism

3.1 How tool groups work in Kira

A Kira MCP tool is a server-side function in the Kira control plane (read or write) that:

1. declares its args plus the injected caller identity;
2. gates on a permission check;
3. delegates to a tenant-scoped helper;
4. for writes, records an in-transaction audit row.

The pattern is visible in the first-party contacts tool group, which uses the shared gateway helpers for caller identity, permission validation, and the tool permission registry. Tools are registered into the served surface via the gateway's tool registry.

Permission slugs. The tool permission registry governs what permissions tool calls require. Integration tools use integration:view (reads) and integration:manage (writes). These are the shipped slugs, established by the reference connector's MCP tools. New partner integrations use these same slugs unless there is a tenant-isolation requirement that demands dedicated <partner>:view/<partner>:manage slugs.

Exposure. Each tool group's visibility per tenant is controlled by a tool-exposure setting. Integration tools default to hidden and must be explicitly enabled for each tenant that has the integration configured, by an admin with feature-flag permissions.

Audit. Every invocation, success or failure, is written to the unified tool-invocation audit ledger, capturing tenant, agent, conversation, tool name, input/output, duration, status, and error code.

3.2 The reference connector: the template to clone

The reference connector is the reference implementation for any external-system tool group:

• Per-tenant connection config
• Typed connection object
• Cached client-credentials token, keyed by apiBase|clientId with a 30-second expiry skew
• SSRF-gated outbound request builder
• Test-connection action
• Read actions (appointments and cases)
• Agent-facing MCP tool layer using integration:view and integration:manage permission slugs

Any new connector for an external system clones this shape:

1. Connector module: typed connection object, client-credentials grant, token cache (keyed apiBase|clientId, refresh on 401 then retry once), SSRF-gated request builder, test-connection action, read and write actions
2. MCP tool layer: agent-facing tools with caller and role gates via permission validation, registered into the gateway's tool registry as <partner> registrations
3. Connection config: either new per-tenant connector fields cloning the reference connector's columns, or a per-tenant MCP-server installation row if the partner hosts their own MCP server

3.3 Storing the connection config: two options

• (A) Clone the connector config fields: add <partner>_enabled, <partner>_api_base, <partner>_client_id, <partner>_client_secret, and any partner-specific fields, mirroring the reference connector's fields. Simplest; matches the reference connector precedent exactly. Recommended when Kira calls the external system's API directly.
• (B) Per-tenant MCP installation: the generic per-tenant MCP installation table already models serverUrl, authType: "oauth2", authCredentials, enabled, priority, rate limits, and health status. Use this if the partner hosts their own MCP server that Kira calls over HTTP instead of Kira calling the external API directly.

Option (A) keeps the external API mapping inside Kira where the canonical model lives; secrets are stored as connection config (sandbox phase) and moved behind the platform secret-reference layer before production.

3.4 Write-back conventions

Write tools must be:

• Idempotent: take a required idempotencyKey; use alternate-key upsert where the external system supports it so a retried agent turn does not duplicate the record
• Audited: every call is logged for both success and error paths; the audit row captures input, output, duration, and error code
• Canonical on return: map the write result to a Kira TimelineEvent/Lead/ServiceCase shape; optionally persist it locally with sourceTable/sourceId pointing back at the external record for provenance

---

4. Data model mapping

Kira's canonical model is the internal target. External system schemas map at the connector boundary and are never leaked into Kira's core domain. The connector's mapper functions translate between external field names and canonical entities.

Generic mapping table:

Kira canonical entity	Kira module	Typical external analog	Notes
Person	CRM	Contact, Patient, Member, User	Primary identity. Linked by external ID (system-assigned GUID or key); governed-merge rule.
Organization	CRM	Account, Practice, Group, Club	Parent entity for Person records.
TimelineEvent (interaction)	Support	Activity, Call, Appointment, Note	Agent-authored write-backs; also persisted locally on the Kira timeline.
TimelineEvent (event / order)	CRM	Event, Fixture, Ticket, Order	Reference data and order history, read-only unless the tenant opts to persist.
TimelineEvent (consent)	CRM	Consent record, Preference column	Opt-in capture; provenance includes tenant/agent/conversation IDs for compliance export.
ServiceCase	Support	Case, Incident, Ticket	Service lifecycle records; maps FHIR Task/ServiceRequest in healthcare contexts.
InteractionSession	Support	Session, Encounter	Scoped to a single agent conversation; maps FHIR Encounter when clinically scoped.
Lead	CRM	Lead, Opportunity, Intent	Unqualified interest or renewal intent; opened by the agent from a conversation.

Boundary rule: external API field names must not appear outside the connector. Connector mappers translate to canonical shapes; the sourceTable/sourceId fields on timeline events point back at the external record for provenance.

Identity linking follows a governed-merge rule: link an external ID to the Kira Person via an external-id record link; never auto-duplicate.

---

5. Inbound webhooks (external system → Kira) Partner onboarding

Kira's existing internal ingress pattern is the template. Ingress routes authenticate a shared bearer secret and hand off asynchronously:

• Kira's ingress auth checks a Bearer or x-workflow-ingress-secret header against the Kira-issued ingress secret.
• Handlers validate the body, schedule the heavy work off the request path, and return 202 with { scheduled: true }.

A per-partner POST /webhooks/<partner>/{connectionId} follows this exact shape:

1. Authenticate the ingress secret (Bearer or x-workflow-ingress-secret header)
2. Validate required fields (tenantId, event, plus partner-specific entity IDs); return 400 if missing
3. Schedule the outreach workflow off the request path
4. Return 202 { scheduled: true, eventId: "..." }

Kira issues the ingress secret; the partner stores it in their webhook or plug-in configuration. This is the internal-secret ingress pattern, distinct from the public chat-channel webhook /webhooks/<channelId>/<connectionId>.

---

6. What a partner must provide

The following checklist applies to any external system integration. Items 1–5 gate Phase 2 (read-only); items 6–7 gate Phase 3 (write-back); item 8 gates inbound webhooks.

For Phase 2 (read-only integration):

1. External system sandbox API endpoint: the non-production base URL for the API Kira will call, including region if relevant
2. Auth credentials for a service account or app registration; at minimum a client ID and client secret (or API key), plus any tenant/directory IDs required by the token endpoint
3. Service account permissions: a least-privilege security role scoped to the tables/entities the integration reads
4. Schema / entity metadata: the real field names, logical names, or endpoint paths for every entity the tools will read, including navigation properties and any custom fields
5. A seeded test record in the sandbox, matching whatever persona the demo uses, so Kira can validate the search → fetch → display chain end to end

Additionally for Phase 3 (write-back):

6. Write permissions on the target entities (interaction/activity log, consent/preference columns, intent capture) added to the service account's security role
7. Idempotency mechanism: alternate key, conditional upsert header, or a deduplication field on the activity/lead tables so retried agent turns do not create duplicate records

Additionally for Phase 4 (inbound webhooks):

8. Ability to call an outbound HTTPS endpoint from the external system (plug-in, automation flow, or webhook config), plus the ability to store and transmit the Kira-issued ingress secret

Also confirm for any phase:

• Service-protection / rate-limit expectations for the sandbox
• API access model (direct external API vs the partner's own façade)
• Residency / region (for data-at-rest and API routing)

---

7. Phasing template (read-only → write-back)

Any new integration follows this phase order. Do not skip to write-back without first validating auth and read-only.

Phase	Scope	Kira work	Partner gate	Exit criteria
1: Demo-sim	Agent with zero integration (KB-only answers)	Tenant, agent, knowledge base	None	Agent answers questions from KB; demoable standalone
2: Connect and read-only	Auth reachability, then read tools	test_connection action (clone the reference connector), read tools, entity mapping	Items 1–5 above	test_connection passes; agent reads live sandbox data
3: Write-back	Write tools (interaction log, opt-in, intent capture)	Write tools, audit, idempotent upsert, canonical TimelineEvent/Lead mapping	Items 6–7 above	Write records visible in external system; retried turns do not duplicate
4: Inbound	External-triggered outreach	Ingress webhook route and workflow (clone the internal ingress pattern)	Item 8 above	External event triggers Kira outreach workflow

Do not skip the connect → read → write ordering. Read-only first proves the auth, egress safety gate, token cache, and entity mapping before any write touches the partner's system of record.

---

8. Shipped-vs-onboarding summary

Shipped in the Kira platform	Per-partner instantiation
MCP gateway POST /mcp with tenant-scoped auth	<partner>_* tool group
Tool pattern: caller identity, permission validation, the tool permission registry	Partner permission entries added to that registry
External-connector precedent: the reference connector and its MCP tools, using integration:view/integration:manage	Partner connection storage and partner MCP tool group
OAuth client-credentials helper with scope, redirect, and timeout handling	Partner token endpoint and scope wiring
Tool-invocation audit ledger	Canonical ServiceCase/TimelineEvent persistence choices per partner
Ingress webhook pattern with shared secret and schedule-and-202	POST /webhooks/<partner>/{connectionId}
Generic per-tenant MCP installation table	Connection storage option B if partner hosts own MCP server

---

9. Worked examples

9.1 Reference connector (EHR): shipped

The reference connector is code-complete and merged in the Kira platform. It is the reference implementation for all patterns in this guide.

• Connector core: typed connection object, cached client-credentials token, SSRF-gated request builder, test-connection action, and read actions for appointments and cases
• Connection config: per-tenant connector fields
• MCP tool layer: agent-facing tools using integration:view and integration:manage permission slugs

Use cases: patient-record lookup, appointment retrieval, and case status, read from and written back to the EHR during a healthcare voice agent conversation.

---

See also: the API Reference tab for the generic endpoint reference.

API Reference

The Kira integration API is a single MCP JSON-RPC endpoint exposed per tenant. Every call is authenticated with a Kira-issued bearer credential and gated by the Kira permission registry.

Machine-readable spec: download the OpenAPI 3.1 spec or the Postman collection. The tables below cover the same surface in prose.

Endpoints

Endpoint	Method	Status	Description
/mcp	POST	Available today	MCP JSON-RPC gateway: tools/list and tools/call
/webhooks/{partner}/{connectionId}	POST	Partner onboarding	Inbound webhook ingress: shared-secret bearer, schedule-and-202

Connector reachability testing (the test_connection action) runs Kira-side during onboarding; it is not a partner-facing REST endpoint.

Your First Tool Call

Three commands take you from credentials to live tool output. Your Kira host and bearer credential are issued at onboarding.

1. Set your credentials:

export KIRA_HOST="https://<your-kira-host>"
export KIRA_TOKEN="<your-bearer-credential>"

2. Discover the tools enabled for your tenant:

curl -s "$KIRA_HOST/mcp" \
  -H "Authorization: Bearer $KIRA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

3. Call one of them:

curl -s "$KIRA_HOST/mcp" \
  -H "Authorization: Bearer $KIRA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"connector_search_record",
                 "arguments":{"phone":"+61400000000"}}}'

A successful call returns HTTP 200 with the tool output in result.content[0].text. A 401 means the bearer credential is missing or invalid; a JSON-RPC error object means the call reached the gateway and was rejected by permissions or validation (see Error Responses below).

Authentication

All requests require a Kira integration bearer token in the Authorization header:

Authorization: Bearer <kira-bearer-token>
Content-Type: application/json

The token is resolved to a tenant and checked against the tool permission registry. Integration credentials are issued during partner onboarding: a bearer credential for the gateway and a signing secret for webhook ingress.

MCP Call Shape

POST /mcp
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 1,
  "params": {
    "name": "connector_getRecord",
    "arguments": { "externalId": "CONTACT-001" }
  }
}

Error Responses

HTTP	JSON-RPC code	Meaning
401	n/a	Missing or invalid bearer token
403	-32600	Tool call blocked by permission registry
404	-32601	Tool name not found for this connector
422	-32602	Invalid tool arguments (schema validation)
502	-32603	External system unreachable or auth failure
200	n/a	Success: check result.content[0].text for tool output

Tool Output Shape

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{ "type": "text", "text": "{...json or prose...}" }],
    "isError": false
  }
}

Webhook Ingress Shape

POST /webhooks/{partner}/{connectionId}
Authorization: Bearer <kira-issued-secret>
Content-Type: application/json

{ ...partner event payload... }

HTTP 202 Accepted

The payload is validated, a workflow trigger is queued, and Kira responds immediately with 202. Processing is async, so the partner should not retry on 202.