Server Mode

With MCP_ENABLED=true, Sovrium generates an MCP tool set from your configuration. Nothing is exposed by default: an entity appears only when its schema declares aiAccess, and only in the shape the connecting role is allowed to see.

Exposed Surfaces

Four kinds of thing become tools.

Surface	Tool name	What it does
User tables	{app}_{table}_{op}	Read, list, create, update, delete records.
Manual automations	{app}_automation_{name}	Invoke an automation with a manual trigger.
Action templates	{app}_action_{name}	Execute one action template.
Admin internals	{app}_auth_* / {app}_system_*	Read-only views of auth and system tables, admin role only.

tools/list is filtered per connection, so a viewer credential is never even told that a delete tool exists. Only manual-trigger automations qualify — a cron or record-change automation has no caller to expose.

Declaring Eligibility

aiAccess is the schema author's declaration of intent. It is deliberately separate from MCP_ENABLED: writing it does not expose anything, and the operator's switch does not expose anything you did not write.

tables:
  - name: contacts
    aiAccess: true

That boolean is the common case — expose the table with defaults. The object form takes over when defaults are not right, and supplying any object is itself the enable signal; there is no enabled field to set.

tables:
  - name: contacts
    aiAccess:
      description: Customer contacts. Use this when the user asks about people.
      operations: [read, list, create, update]
      fieldExposure: permissioned
      annotations:
        readOnly: false
        destructive: false

Property	Meaning
description	The tool description the model reads. Up to 2000 characters.
operations	Subset of read, list, create, update, delete. Tables default to all five.
fieldExposure	permissioned (default), all, or whitelist.
whitelistFields	Which fields, when fieldExposure: whitelist. Required and non-empty in that mode.
annotations	Risk hints — see below.
requireConfirmation	Force the destructive hint regardless of operation type.

Automations and action templates accept the same block but ignore operations: each exposes a single invocation tool.

Field Exposure

Mode	Fields in the tool schema
permissioned	Only what the connecting role may read or write. The default.
all	Every field, still subject to field-level RBAC at call time.
whitelist	Only the names in whitelistFields.

permissioned is right almost always: it means a viewer and an admin connecting to the same table see different tool schemas, without you maintaining two declarations. Reach for whitelist when a table holds columns that are readable by the role but simply not the AI's business.

Tool Risk Annotations

Annotations compile into the MCP tool definition so a client can decide whether to run a call silently or ask its user first. They map one-to-one onto the protocol's hints:

Annotation	MCP hint	Says
readOnly	readOnlyHint	Reads only — safe to auto-approve.
destructive	destructiveHint	Destroys or sends something — ask first.
idempotent	idempotentHint	Calling twice is safe; no duplicate side effects.
openWorld	openWorldHint	Reaches outside the app — external API, network call.

Left unset, sensible values are derived from the operation type, and MCP_CONFIRM_DESTRUCTIVE (on by default) additionally marks delete tools and non-idempotent automations as destructive.

The case worth setting by hand is the automation that is technically idempotent but practically irreversible — sending an email, charging a card. requireConfirmation: true forces the destructive hint on those regardless of what the operation type would imply.

Related Pages

• MCP Overview — enabling the server.
• Connecting a Client — pointing an assistant at it.
• Auth, RBAC & Rate Limiting — the enforcement behind the filtering.
• Tables Overview — where aiAccess sits on a table.
• Actions — action templates as tools.