Integrating with Kira — Technical Guide

Audience: Partner engineering teams and integration developers Status: Draft · 2026-07-02 Kira platform basis: Convex control plane (ADR-011), WorkOS identity, MCP tool-group runtime

How to read this doc. Every platform mechanism described here (MCP tool groups, the MCP gateway endpoint, tenant/permission model, ingress webhooks, the OAuth client-credentials helper, per-tenant connection storage) is grounded in shipped code and cited as path:line. Per-partner instantiations — the connector file, the tool list, the external API calls — are marked Partner onboarding and specified here against the shipped reference implementation (the production EHR connector, which does exist and is the template to clone). The EngageRM and the reference connector worked examples in §9 apply this platform to specific systems of record; the platform mechanics are identical for any external system.

---

0. Reviewer's guide (start here)

Related doc set:

1. This guide — the code-grounded how: auth, the MCP tool-group mechanism, the connector pattern, data-model mapping, ingress webhooks, the partner checklist, and phasing template.
2. API reference — docs/proposals/2026-07-02-kira-integration-api-reference.md. The generic endpoint/OpenAPI spec: POST /mcp, the per-partner inbound webhook pattern, error shapes, and auth headers. Skim / reference.
3. Worked examples — EngageRM-specific detail lives in docs/proposals/2026-06-30-engagerm-technical-integration-guide.md, docs/proposals/2026-06-30-engagerm-api-reference.md, docs/proposals/2026-06-30-engagerm-integration-framework.md, and docs/plans/2026-06-30-engagerm-afl-sandbox-tenant-design.md.

Decisions that apply to all connectors:

1. Permission slugs. Use integration:view / integration:manage. (the reference connector scheduling MCP tools, merged to the Kira platform) uses these same slugs after Max's merge rework — they are the shipped precedent in the tool permission registry (the Kira MCP runtime). Add dedicated <partner>:* slugs only if tenant-level isolation is later required.
2. Connection storage. Clone ehrConfig connector_* fields (Kira calls the external API directly; recommended) vs a mcpServerInstallations row (only if the partner hosts its own MCP server). See §3.3.
3. Write ordering. Always prove auth and read-only before enabling write-back. See §7.

Citation verification (all Available today claims verified against kira-ei-demo checkout and `origin/the Kira platform):

• the Kira control plane ✓ · Kira MCP runtime ✓ · the Kira control plane ✓
• the Kira control plane ✓ (the client-credentials token helper confirmed at that exact line)
• the reference connector ✓ (corrected from earlier drafts: :105→:108 for grantConnectorToken, :113 for the SSRF check inside grantConnectorToken)
• the Kira control plane ✓ · the Kira control plane (corrected from 7149) · the Kira control plane (corrected from 7068) · the Kira control plane ✓ · the Kira control plane ✓
• the Kira control plane ✓

---

1. Overview

Kira is the system of engagement and orchestration. Any external system — EHR, CRM, ERP, ticketing platform, 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 a Convex action, 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 (text diagram)

                         Kira (Convex control plane)
  ┌───────────────────────────────────────────────────────────────────────┐
  │                                                                       │
  │  Agent runtime (voice / chat)                                         │
  │        │                                                              │
  │        │ tools/call  <partner>_search_record { ... }                  │
  │        ▼                                                              │
  │  MCP gateway endpoint  POST /mcp     Available today │
  │        │  · WorkOS bearer → workosOrgId → tenant                     │
  │        │  · resolves caller identity + role                          │
  │        ▼                                                              │
  │  <partner>_* tool group  Partner onboarding                       │
  │   (Kira MCP layer<partner>.ts — clone of raintree.ts)        │
  │        │  · permission validation(ctx, caller, "integration:*")  │
  │        │     Available today           │
  │        │  · load per-tenant connection config                         │
  │        │    (Partner onboarding cloned from ehrConfig connector_* fields)      │
  │        ▼                                                              │
  │  <partner>.ts action ─── the client-credentials token helper() ──► Partner    │
  │     │
  │        │  Bearer <access_token>                             OAuth IdP  │
  │        ▼                                                              │
  │  validateWebhookUrl() SSRF gate  Available today  │
  │        │                                                              │
  │        │  GET/POST  https://<partner-api-host>/... ──────────────────┼──► External system
  │        ▼                                                              │
  │  recordToolInvocation() audit    Available today   │
  │   → mcpToolInvocations table                  │
  │                                                                       │
  │  Inbound (optional, later): Partner onboarding                    │
  │  POST /webhooks/<partner>/{connectionId}                              │
  │   auth: WORKFLOW_INGRESS_SECRET bearer  Available today │
  │   → schedules outreach workflow, returns 202                          │
  └───────────────────────────────────────────────────────────────────────┘

---

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 helper: the client-credentials token helper() in the auth helper. The filename carries a fhir prefix because it was first written for FHIR/EHR integrations, but the implementation is fully generic: it accepts any token endpoint, scope, client ID, and client secret, and is reused by the the reference connector EHR connector today (see §3.2).

The helper:

• assembles the x-www-form-urlencoded body (the Kira control plane),
• forwards an optional scope ,
• follows region redirects manually ,
• enforces a 10s timeout (:28, :94),
• throws on non-2xx or a missing access_token .

The the reference connector connector wires this helper end-to-end today (the reference connector, grantConnectorToken → the client-credentials token helper), including an in-isolate token cache keyed by apiBase|clientId with a 30s expiry skew (the reference connector, authenticateConnector). Any new connector clones this pattern: same helper, partner-specific token endpoint and scope, per-isolate token cache with forceRefresh on 401.

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

Every outbound token/API URL is SSRF-validated before the fetch via validateWebhookUrl() (the Kira control plane), exactly as the reference connector does (the reference connector, inside grantConnectorToken). 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, POST /mcp, handler kiraMcpEndpoint (POST /mcp).
• The endpoint resolves a WorkOS bearer → workosOrgId → Kira tenant, and returns a 401 with WWW-Authenticate when the token is missing/invalid (POST /mcp, :437).
• Inside each tool, permission validation(ctx, caller, permission) (the Kira MCP runtime) resolves the caller's canonical user, looks up their membership role in the tenant, caps platform-manager roles , and asserts the tool's permission slug . No membership or missing permission → ConvexError.

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 (§2.1) plus, optionally, the inbound webhook (§5).

---

3. The MCP tool-group mechanism

3.1 How tool groups work in Kira (grounded in code)

A Kira MCP tool is a Convex internalQuery (read) or internalMutation/internalAction (write) that:

1. declares its args plus ...callerArgs (the injected caller identity) — the Kira MCP runtime;
2. gates on a permission via permission validation(...) — the Kira control plane;
3. delegates to a tenant-explicit *ForTenant helper;
4. for writes, records an in-transaction audit row.

The pattern is visible in the first-party contacts tool group (the Kira MCP runtime), which uses defineMcpQuery / defineMcpMutation from the convex-mcp-gateway package and imports callerArgs, permission validation, and the tool permission registry from shared.ts. Tools are registered into the served surface via kiraMcpTools in the Kira MCP runtime.

Permission slugs. The central map the tool permission registry (the Kira control plane) governs what permissions tool calls require. Integration tools use integration:view (reads) and integration:manage (writes) — the Kira control plane. These are the shipped slugs, established by (the reference connector scheduling MCP tools, merged to the Kira platform). 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 via KIRA_MCP_TOOL_EXPOSURE (the Kira control plane). Integration tools default to { defaultExposed: false, module: "<partner>_crm" } and must be explicitly enabled for each tenant that has the integration configured. An admin with feature_flag:manage sets an mcpToolExposure row { toolName, exposed: true } for the target tenant.

Audit. Every invocation — success or failure — is written to the unified mcpToolInvocations audit ledger (the Kira control plane) via recordToolInvocation (the Kira control plane), capturing tenant, agent, conversation, tool name, input/output, duration, status, and error code.

3.2 The reference connector (the reference connector — template to clone)

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

• Per-tenant connection config in ehrConfig (connector configuration, :134-138)
• Typed connection object: ConnectorObject (the reference connector)
• Cached client-credentials token via the client-credentials token helper (the reference connector, grantConnectorToken), cache keyed by apiBase|clientId with a 30s expiry skew (the reference connector, authenticateConnector)
• SSRF-gated outbound request builder: ConnectorObject (the reference connector)
• Test-connection action: testConnection (the reference connector)
• Read actions: getPatientAppointments (the reference connector) / getPatientCases (the reference connector)
• Agent-facing MCP layer: the Kira MCP runtime (on the Kira platform, merged via , uses integration:view/integration:manage)

Any new connector for an external system clones this shape:

1. the Kira control plane — typed connection object, client-credentials grant, in-isolate token cache (keyed apiBase|clientId, refresh on 401 then retry once), SSRF-gated request builder, testConnection action, read and write actions
2. the Kira MCP runtime — internalAction tools (external HTTP calls must be actions, not queries/mutations), caller/role gate via permission validation, registrations exported as <partner>Registrations and spread into kiraMcpTools in gateway.ts
3. Connection config — either as new fields on ehrConfig cloning the connector_* columns (the Kira control plane), or as a mcpServerInstallations row if the partner hosts their own MCP server (the Kira control plane, managed via createInstallation at the Kira control plane, updateInstallationCredentials at the Kira control plane)

3.3 Storing the connection config — two options

• (A) Clone ehrConfig — add <partner>_enabled, <partner>_api_base, <partner>_client_id, <partner>_client_secret, and any partner-specific fields, mirroring the connector_* fields (connector configuration, :134-138). Simplest; matches the the reference connector precedent exactly. Recommended when Kira calls the external system's API directly.
• (B) mcpServerInstallations row — the generic per-tenant MCP installation table (the Kira control plane) already models serverUrl, authType: "oauth2", authCredentials, enabled, priority, rateLimitRequests, rateLimitWindowMs, and health status. Managed via createInstallation (the Kira control plane) / updateInstallationCredentials (the Kira control plane). 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-ref layer (/internal/secret-refs/*, POST /mcp) 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 — call recordToolInvocation (the Kira control plane) 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 via the Kira control plane with sourceTable/sourceId pointing back at the external record for provenance

---

4. Data model mapping

Kira's canonical model (Unified Charter) 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 via recordCrmTimelineEvent.
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 file. Connector mappers translate to canonical shapes; the sourceTable/sourceId fields on crmTimelineEvents point back at the external record for provenance.

Identity linking follows the Charter's 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. Internal ingress routes authenticate a shared bearer secret and hand off asynchronously:

• isAuthorizedWorkflowIngress(request) checks a Bearer/x-workflow-ingress-secret header against WORKFLOW_INGRESS_SECRET (POST /mcp).
• Handlers validate the body, schedule the heavy work off the request path, and return 202 (see the EI ingress POST /internal/ei/orchestrate, POST /mcp, which returns { scheduled: true } with status 202).

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

1. Authenticate the ingress secret (check Bearer or x-workflow-ingress-secret header against WORKFLOW_INGRESS_SECRET)
2. Validate required fields (tenantId, event, plus partner-specific entity IDs); return 400 if missing
3. ctx.scheduler.runAfter(0, ...) to schedule the outreach workflow off the request path
4. Return 202 { scheduled: true, eventId: "..." } (matches POST /mcp)

Kira issues the ingress secret; the partner stores it in their webhook/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: client ID + 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
0/2 — Connect + 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 + workflow (clone /internal/ei/orchestrate pattern)	Item 8 above	External event triggers Kira outreach workflow

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

---

8. Grounded-vs-proposed summary

Grounded in shipped code (cite)	Per-partner instantiation
MCP gateway POST /mcp + WorkOS-scoped auth (POST /mcp, POST /mcp)	<partner>_* tool group (the Kira MCP runtime)
Tool pattern: callerArgs, permission validation, the tool permission registry (the Kira MCP runtime)	Partner permission entries added to that map
External-connector precedent — the reference connector connector (the reference connector; connector configuration) + the reference connector MCP tools (the Kira MCP runtime, merged via to the Kira platform, using integration:view/integration:manage)	<partner>Config connection storage; <partner>.ts MCP tool file
OAuth client-credentials helper w/ scope + redirects + timeout (the auth helper — generic despite the fhir filename)	Partner token endpoint + scope wiring
Tool-invocation audit ledger (the Kira control plane; the Kira control plane)	Canonical ServiceCase/TimelineEvent persistence choices per partner
Ingress webhook pattern w/ shared secret + 202 schedule (POST /mcp)	POST /webhooks/<partner>/{connectionId}
Generic per-tenant MCP installation table (the Kira control plane; the Kira control plane)	Connection storage option B if partner hosts own MCP server

---

9. Worked examples

9.1 the reference connector (EHR — shipped)

The the reference connector connector is a live, merged integration on the Kira platform. It is the reference implementation for all patterns in this guide.

• Connector core: the reference connector — ConnectorObject , grantConnectorToken → the client-credentials token helper , in-isolate token cache (authenticateConnector, :141-180), SSRF-gated request builder ConnectorObject , testConnection , getPatientAppointments , getPatientCases
• Connection config: connector configuration — connector_* fields at :62-66 and :134-138
• MCP tool layer: the Kira MCP runtime (on the Kira platform, merged via ), using integration:view / integration:manage permission slugs

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

9.2 EngageRM (Dynamics 365 / Dataverse — proposed)

EngageRM is a Dynamics 365 / Dataverse ISV for sports and membership organizations. The proposed integration follows the the reference connector connector pattern, adapted for Dataverse OData v4 + Microsoft Entra ID client-credentials.

Auth specifics:

• Token endpoint: https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token, grant client_credentials, scope https://{org}.crm.dynamics.com/.default (Microsoft Learn — Use OAuth with Dataverse, retrieved 2026-06-30)
• External API: Dataverse Web API v9.2 (https://{org}.crm.dynamics.com/api/data/v9.2/), OData v4 (Microsoft Learn — Compose HTTP requests, Web API v9.2, retrieved 2026-06-30)

Proposed tools (8-tool set): engagerm_test_connection, engagerm_search_member, engagerm_get_member, engagerm_get_member_tickets, engagerm_get_fixtures, engagerm_log_interaction, engagerm_capture_optin, engagerm_create_lead.

Demo scenario: AFL sports membership — minotaurs-demo tenant (fictional Port Meridian Minotaurs), "Theo" inbound voice fan-assist agent.

Full EngageRM-specific detail:

• Technical integration guide: docs/proposals/2026-06-30-engagerm-technical-integration-guide.md
• API reference: docs/proposals/2026-06-30-engagerm-api-reference.md
• AFL sandbox tenant design: docs/plans/2026-06-30-engagerm-afl-sandbox-tenant-design.md
• Integration framework / substrate decision: docs/proposals/2026-06-30-engagerm-integration-framework.md

---

See also: docs/proposals/2026-07-02-kira-integration-api-reference.md for the generic endpoint/OpenAPI reference.

API Reference

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

Full OpenAPI 3.1 spec available separately. Request the spec YAML or Postman collection from your KeyReply integration contact. The tables below cover what partner engineers need to get started.

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
/v1/connectors/{id}/test	POST	Available today	Reachability + auth probe for a stored connector configuration
/v1/connectors/{id}/tools/{tool}	POST	Available today	Direct tool invocation bypassing agent (for testing)

Authentication

All requests require a WorkOS bearer token in the Authorization header:

Authorization: Bearer <workos-session-token>
Content-Type: application/json

The token is resolved to a tenant and checked against the tool permission registry. Tokens are standard WorkOS session JWTs — obtain via the WorkOS login flow.

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	—	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	—	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 — the partner should not retry on 202.

EngageRM × AFL Sports Membership

The full EngageRM worked example — minotaurs-demo tenant design, persona, agent prompt, 8-tool set, phased build plan, and partner handover checklist — is available as a companion document. Ask your KeyReply integration contact for access.

This tab is reserved for partner-specific design walk-throughs delivered during the onboarding call.