Aevah MCP surface

Tool classes

Agents cannot promote themselves between classes.

• Read: Returns data and changes nothing. Executes directly under the caller's permissions.
• Propose: Produces a change proposal for a human to approve. Nothing changes until a person with the required authority approves it. Most agent-initiated change belongs here.
• Execute: Performs a governed change under explicit prior confirmation, reauthorized at the moment it runs. Confirmation is single-use, bound to the specific operation, and cannot be reused or broadened.

Tool families

• Catalog discovery: Returns the tools, versions, classifications, and permissions available to the caller.
• Data navigation: Returns authorized entities, relationships, definitions, and business context.
• Quality intelligence: Returns quality standards, failed checks, affected records, and supporting evidence.
• Matching and survivorship insight: Returns candidate records, comparisons, proposed outcomes, and the evidence available for review.
• Governance memory: Returns definitions, policies, ownership, decisions, approvals, and audit history.
• Publication and activation: Returns publication status, eligible targets, activation outcomes, and correlation identifiers.
• Operations: Returns operation status, progress, cancellation state, and per-record outcomes.

MCP primitives

• Tools: supported.
• Resources: supported, read-only governed artifacts.
• Prompts: supported, curated task templates.
• Notifications: supported, tool-list changes and operation progress.
• Sampling: not supported by design — Aevah does not request inference from the connecting client.
• Elicitation: not supported by design — consequential actions return a proposal for human approval rather than negotiating mid-call.

MCP Apps

When an agent reaches a decision only a person should make, Aevah hands back a usable interface rather than a wall of JSON. An agent proposing a merge returns a review surface showing the candidate records side by side, which attribute value wins and why, and approve or reject controls — rendered directly in the agent's own environment. The person decides on real evidence, in context, and the decision is captured in the audit trail. The interface is a rendering surface, never an authority: every approval is reauthorized against the approver's permissions before anything changes, and the surface never receives values the viewer is not cleared to see. Review surfaces cover merge and match review, survivorship explanation, data quality triage, mapping suggestion review, and generic proposal approval.

Versioning

Breaking changes publish a new tool version; existing versions are never altered. Deprecation is signalled in tool metadata with a replacement pointer.

Denials state what was required, never what exists.

An error never reveals the presence or content of a record you may not see.

401 — no valid identity
{ "status": 401, "error": "unauthenticated",
  "message": "No valid identity was presented.",
  "correlationId": "3f9c1a7e-..." }

403 — authenticated, lacks the permission
{ "status": 403, "error": "forbidden",
  "message": "Permission 'connected_system.manage' is required.",
  "requiredPermission": "connected_system.manage",
  "correlationId": "8b21d4c0-..." }

403 — policy denial
{ "status": 403, "error": "policy_denied",
  "message": "Export is not permitted for Restricted content.",
  "policy": "classification.export",
  "classification": "Restricted",
  "correlationId": "c47a09fe-..." }

409 — approval required
{ "status": 409, "error": "approval_required",
  "message": "This change requires steward approval before execution.",
  "proposalId": "prop_9d3f21",
  "requiredPermission": "steward.approve_merge",
  "correlationId": "5e8f3b12-..." }