Ailysi MCP Governance Document

This document governs the Ailysi Model Context Protocol (MCP) server — the interface through which external AI clients (Claude, ChatGPT, Cursor, and custom MCP-compatible clients) connect to and act on Ailysi platform data on behalf of an authenticated app user.

1.1 What the MCP server is

The Ailysi MCP server is published at /api/mcp on the app's own domain. It exposes the platform's capabilities as discrete tools — one per entity operation, one per exposed in-app agent, and one per explicitly registered custom function tool. The server is generated from base44/mcp/config.json and is active only on the published app. It is not a separate service, proxy, or parallel data store.

1.2 Access model — OAuth (sign-in required)

Access is OAuth-gated (auth: "oauth"). There is no anonymous or public path. An AI client never holds a standing platform credential; instead, each connection opens the Ailysi consent page (/oauth/consent), where the end user signs in with their own Ailysi account and explicitly approves the access request. The assistant only ever acts as that signed-in user — every tool call inherits that user's role, tenant scope, and Row-Level Security (RLS) permissions.

1.3 Consent & connect flow

End users discover how to connect an AI client via the in-app /connect page, which resolves the live server URL from the active domain and provides setup steps for Claude, ChatGPT, Cursor, and custom clients. The OAuth consent page (/oauth/consent) lists the concrete tools the client will be granted and posts an atomic approve/deny decision. A consent handle is single-use; once consumed it cannot be replayed.

1.4 Who can access

Any authenticated Ailysi user may connect an AI client. Access is scoped by the user's role (admin / partner / user) and tenant membership. No role or tenant is elevated by connecting through MCP — the protocol is a transport, not an authority.

The MCP tool surface is engineered to the minimum an AI client needs, with PII, financial, and internal-log data protected by explicit overrides. Exposure is opt-out: every entity and agent is exposed by default unless narrowed here.

2.1 Tool surface tiers

The published tool set is partitioned into three tiers:

• Full CRUD. Entities with no override — exposed for read, create, update, and delete, gated by RLS. Reserved for low-sensitivity operational entities the AI legitimately acts on.
• Read-only. Entities narrowed to ["read"] — the AI can look up but never mutate. Applied to all PII business records (applicants, partners, employers, reservations, PCC, interviews, agreements, invoices) and all financial/commission ledgers.
• Opted out. Entities set to [] — no tool is generated; the entity is invisible to AI clients. Applied to internal config, governance, workflow, automation, credential-bearing, and all log/audit entities.

2.2 Protected data classes

The following classes are never writable, and most are not exposed at all, via MCP:

2.3 Agent exposure

In-app agents are exposed as message_<agent> tools, gated by the signed-in user's permissions. The copilot agent is excluded (excluded_agents) to prevent autonomous execution paths from being reachable through the external MCP surface. Agent names are frozen at publish; agent behavior (prompt, tools, skills) remains live.

2.4 Custom function tools

No backend function is exposed as a custom MCP tool by default. Functions that mutate state, trigger deployments, or move money are deliberately excluded from the external surface. Adding a function tool requires a governed change request (§3.4), an explicit tools.functions[] entry with a hand-authored input schema, and honest destructive/idempotent annotations.

The MCP server is a published, versioned surface. This section defines change management, token invalidation, audit, incident response, and review cadence.

3.1 Publish & change management

Only the published config is active. Any edit to base44/mcp/config.json — including an opt-out narrowing or a new entity auto-exposed at the next publish — requires republishing the app. Under opt-out, publishing an app with a new entity or agent is itself a surface change and is treated identically to an explicit config edit.

3.2 Token invalidation

Every change to the exposed tool set invalidates the OAuth tokens held by connected AI clients. Each client must re-authorize after a surface change. Communicated changes therefore carry a re-authorization obligation; the /connect page includes a "refresh the connector after we ship changes" notice to set this expectation with end users.

3.3 Audit & accountability

MCP tool calls execute as the signed-in user and are subject to the same audit logging as in-app actions. Consent grant/deny decisions are atomic and single-use; a consumed handle cannot be replayed. Platform-side MCPConnectorLog (itself opted-out of the tool surface) records connection events for administrative review.

3.4 Change request process

1. 1Submit a change request specifying the entity/agent/function and the proposed override (full / read-only / opt-out) or new custom tool.
2. 2Platform governance reviews PII, financial, and security impact; read-only is the default for any new business entity.
3. 3Config edit lands in base44/mcp/config.json via protected-branch PR with admin approval.
4. 4App is republished; connected clients are notified of the re-authorization obligation.

3.5 Incident response

3.6 Review cadence

This document and base44/mcp/config.json are reviewed quarterly, and ad-hoc whenever a new entity, agent, or function is added to the platform. The review confirms that every new capability received an explicit override decision rather than inheriting full CRUD exposure by default.