# The Integrations

**Track 11 of 11 · inward and outward — MCP, APIs, plug-ins, and building on Kiduna · v5.6**

Integration runs in two directions, and this track holds both: **inward** — the MCP servers, APIs, and local agents we connect to, so allies can act in the world; and **outward** — our own API and MCP server, so anyone can build on us. The permission model for both directions already exists: the Tool node, grants, and the four access levels ([Foundation](foundation.html)), checked by the graph service on every call. Nothing in this track invents new access; it plugs new parties into the access that exists.

---

## 1. Inward — what we connect to

**MCP servers, attached in [Studio](surfaces.html), scoped to containers.** A member (or a Builder acting for an organization) connects an MCP server and attaches it to a specific relationship, guild, alliance, or organization — the container is the scope. A scheduling server attached to an alliance serves that alliance's work and nothing else; a payments tool attached to an organization acts only inside its treasury rules. The running list of interesting servers is maintained as wisdom (a living, curated inventory by category — payments and commerce, calendars and scheduling, docs and storage, social and messaging, web and search, creative tooling, dev tools) rather than frozen in this spec.

**Local agents on the member's own machine — the package protocol.** Studio interoperates with **Claude Cowork / Claude Code and OpenAI Codex** running locally over a defined **package-passing protocol**, modeled on the dispatch protocol we run between our own sessions: Studio hands out a self-describing package (context, the ask, constraints, where to return), the coding agent works it in its own environment, and the result returns as a package Studio unpacks into the graph — the exchange recorded like any other work. The member's machine stays theirs; the ally coordinates, it doesn't colonize.

**The first Institution integration: Lightbrush.** The working pattern for bringing an outside stack in ([Institutions](institutions.html)): Lightbrush LLC's creative agents and tooling (Dowbot, Zhowbot, Digital Dolly, RenderDeck, the audio system) integrate into The Ceremony Machine with Elias as forward-deployed engineer — Lightbrush's IP stays Lightbrush's, the integration work is ours, and usage-based distributions flow from the duna's treasury per its recorded configuration. Every future Institution integration should be recognizable from this shape.

**Channels are integrations too.** Telegram, Bluesky, email, the browser ([Express](surfaces.html)) — one system presence per channel ([Orchestration §3](orchestration.html)), thin adapters, identity and permission held in the middle tier.

## 2. Outward — building on Kiduna

**Our own API and our own MCP server.** Every action the system can perform is already a registered graph command ([Actions](actions.html)); the outward surface exposes those commands as an API and as MCP tools — so Claude Code, Codex, and any MCP-capable client can operate the parts of Kiduna a member grants them. New apps, new websites, new tools, or just more features: all of it builds against the same commands the first-party products use.

**No privileged path.** Outside callers are permission-checked by the graph service exactly like internal ones: the four levels, the grants, instructions-only-from-your-own-member, structural recusal, the receipt rule — all of it holds whether the caller is our Flutter app or someone's weekend project. The one account everything needs is [kidunaverse.com](surfaces.html): third-party apps authenticate against it, and their actions trace in the same audit trail the protocol browser walks.

**Creators and Builders open doors deliberately.** Opening part of Kiduna to an outside tool is a grant like any other — scoped, stated, revocable in one sentence, and disclosed where it acts.

## 3. The rule that keeps it safe

One sentence, both directions: **an integration is a tool under grants, never a party with standing.** It cannot vote, cannot hold sovereignty, cannot receive instruction-weight from anyone but the member who granted it, and everything it does is traced. If a proposed integration can't live inside that sentence, it isn't an integration — it's a membership question, and those go through [Roles](roles.html) and [Protocol](protocol.html).

## 8. The outward stack, specified — the API, the MCP server, and the plug-ins · 2026-07-14

The outward direction now has its build specification. The organizing principle, adopted as-is: **the Kiduna MCP server is the platform product; the Codex and Claude plug-ins are elegant clients of it.** Business logic never lives in markdown files; every agent client gets the same permission and audit model; Kiduna becomes infrastructure for agentic organizations, not a bundle of prompts.

**The pieces.** The **Kiduna API** (at **api.kiduna.ai**) is the platform and source of truth. The **MCP server**, hosted at **mcp.kiduna.ai/mcp** as a remote HTTP server with OAuth, is the secure, agent-friendly access layer — the open interoperability surface Codex, Claude Code, ChatGPT, and future agent clients all speak. **Skills** are reusable workflow instructions; **commands** are explicit shortcuts (`/kiduna:status`); **agents** are specialists for delegated jobs; **hooks** are sparse automatic safety checks; **plugin manifests** are packaging.

### The MCP server

Purpose-built tools only — never generic database access, never a broad `execute_action`. Six families:

- **Identity and authority** — `get_my_identity` · `get_effective_permissions` · `list_my_delegations` · `preview_delegation` · `grant_delegation` · `revoke_delegation` · `list_agent_activity`
- **People and relationships** — `search_people_and_agents` · `get_profile` · `list_connections` · `request_connection` · `request_introduction` · `list_invitations` (results respect privacy and relationship visibility)
- **Groups and organizations** — `list_my_organizations` · `get_organization_context` · `create_working_group` · `invite_member` · `change_member_role` · `list_members` · `get_governance_rules`
- **Initiatives and coordination** — `list_initiatives` · `create_initiative` · `get_initiative_context` · `create_task` · `assign_task` · `update_task` · `post_update` · `propose_action` · `record_decision`
- **Decisions and governance** — `create_proposal` · `list_open_proposals` · `preview_vote` · `cast_vote` · `record_consent` · `get_decision_history`
- **Notifications and auditability** — `list_notifications` · `mark_notification_read` · `get_audit_events` · `explain_action_authority`

Every agent action must answer: who is acting · on whose behalf · within which organization · under what mandate · with which permissions · when that authority expires. **A Kiduna agent never inherits every permission its human possesses.** Every write returns an audit ID, acting identity, organization, timestamp, and the authority used. Financial, membership, publishing, voting, and irreversible actions require explicit confirmation — the preview/commit separation, exactly the ACTIONS grammar the Field already speaks.

### Authentication and safeguards

OAuth 2.1 with authorization code + PKCE for people; client credentials only for explicitly registered service agents. Granular scopes (`identity:read` · `profile:read` · `relationships:read/write` · `organizations:read/write` · `initiatives:read/write` · `decisions:read/write` · `delegations:read/write` · `audit:read`). Binding safeguards: short-lived access tokens with rotating refresh · organization- and resource-level authorization on every tool call · no tokens in the plugin repo, no token passthrough downstream · idempotency keys on writes · rate limits per person, agent, organization, and installation · immutable audit events · strict tenant isolation · minimal, paginated responses. Each tool declares honest MCP annotations (`readOnlyHint` · `destructiveHint` · `idempotentHint` · `openWorldHint`) — hints for client approval UX, never substitutes for server-side authorization.

### One repository, two native plug-in packages

A monorepo (`kiduna-agent-plugins/`) with a common core and thin platform adapters: `.codex-plugin/plugin.json` and `.claude-plugin/plugin.json` manifests, both marketplaces, `.mcp.json`, `.app.json` reserved for the hosted ChatGPT integration, and shared `skills/` (SKILL.md is the open, portable format) with platform-generated `commands/`, `agents/`, and `hooks/` — plus `packages/mcp-server`, `packages/api-client`, `packages/schemas`. Skills shared verbatim; commands, agents, and hooks generated from shared source into each platform's schema.

**The first eight skills** (most important journeys, not thirty): `kiduna-get-oriented` · `kiduna-find-collaborators` · `kiduna-form-a-group` · `kiduna-launch-an-initiative` · `kiduna-run-a-decision` · `kiduna-coordinate-work` · `kiduna-delegate-to-an-agent` · `kiduna-audit-agent-activity`. A second plug-in, `kiduna-developer`, later teaches coding agents to build on Kiduna.

**Specialists, after the workflows are stable:** Kinship Mapper (relationships and collaborators) · Organization Steward (groups, roles, governance) · Initiative Coordinator (plans, tasks, decisions) · Authority Auditor (delegations and agent activity). Agents orchestrate skills and MCP tools — they never carry secret capabilities the MCP permission system doesn't grant.

**Commands:** `/kiduna:status` · `/kiduna:people` · `/kiduna:form-group` · `/kiduna:launch` · `/kiduna:decide` · `/kiduna:delegate` · `/kiduna:audit` — skills stay usable without them.

**Hooks, sparse and predictable** (the Vercel lesson — lightweight session-start, never inject-everything-every-turn): SessionStart (is this repo connected to a Kiduna organization or initiative? short status) · PreToolUse (block or warn on a Kiduna write without a clear organization or mandate) · PostToolUse (record a local audit reference) · Stop (remind about unpublished changes or unfinished delegated work). Retrieve context on demand; shared hook scripts, separate per-platform hook configs.

### Build order and alignment

The sequence: identity/organization/delegation/audit models → authenticated API → read-only remote MCP → OAuth + scopes → small set of safe write tools with preview/commit → shared SKILL.md workflows → the two manifests → platform commands/agents/minimal hooks → fixtures and MCP contract tests → local testing → a private Kiduna marketplace for early users → real usage → the OpenAI and Anthropic public directories (production branding, support/privacy/terms, accurate annotations, starter prompts, five positive + three negative test cases).

Alignment with the operating graph: the MCP server is an **ecosystem client of the Graph Command Service, never a second policy boundary** — "delegations" in MCP vocabulary are the graph's grants and mandates; every write lands as a typed ActionRequest and returns the Record's audit reference. The **kiduna.md** convention (companion to CLAUDE.md and AGENTS.md) lets packages carry network-validatable codes so Claude, OpenAI, and other clients can verify provenance over the network — a trusted loop, open but verifiable.

---

*Changes in v5.6: the outward stack specified — API at api.kiduna.ai, the remote MCP server at mcp.kiduna.ai, the two-platform plug-in monorepo, first eight skills, safeguards, and the build order (from the plug-in architecture brief, 2026-07-14). v5.2: the Studio↔Claude Code/Codex package-passing protocol specified; Lightbrush recorded as the first Institution integration. v5.0: track created. Full history: [versions](versions/index.html).*
