Skip to content

MCP Server ​

Overview ​

ODP includes a built-in Model Context Protocol (MCP) server that enables AI agents and LLMs to interact with ODP data and schema through a standardized tool-calling interface.

The MCP server exposes ODP's data operations (CRUD on collections, schema management, files, users, access control, settings, versions, activity, workflow operations, read-only views of AI apps and knowledge bases, notification templates and delivery logs) as typed tools that can be discovered and called by any MCP-compatible AI client (Claude, ChatGPT, etc.). Extensions can add their own tools through the mcp.tools service ref (see Extension tools).


Architecture ​

ODP serves the tools on two endpoints. Both read the same tool catalog and apply the same module settings.

1. Full MCP Protocol (via OdpMCP) ​

GET /mcp and POST /mcp — routes using OdpMCP.handleRequest() implement the full JSON-RPC message protocol per the MCP specification. Each request creates a fresh Server instance and FastifyTransport to avoid connection conflicts with concurrent requests. This is the endpoint an MCP client (Claude, etc.) connects to. It serves two tool modes: registry mode (default) and the flat tool list (mcp_default_tool_mode = 'flat' or ?tool_mode=flat).

2. Admin JSON route ​

POST /server/mcp — a plain admin route with a simplified { tool, params } body and a { data } response. It is not an MCP transport: it runs one tool and returns its result as JSON.

Tool catalog and dispatcher ​

File (service/api/src/modules/mcp/)Role
catalog.tsMcpCatalog: the core tools first (buildTools(), which spreads in the core module tools), then the tools registered through mcp.tools. Nothing is snapshotted: list() / get() / has() read the sources on every call, so a newly registered tool is served on the next request. A lookup by name always finds the core tool first.
dispatcher.tsavailableTools() (what a caller sees), resolveTool() and callTool(): resolve the visible tool, check its P9 scope, run the handler. Every /mcp call (flat mode and the registry-mode gateways) goes through callTool.
tool-scope.tsassertToolScope() (P9 collection checks from each tool's scope) and deletesData() (delete gating).
registry.ts / provide.tsThe mcp.tools registry and its service-registry facade.
toolsets.tsTool groups (?toolsets=, x-mcp-toolsets, mcp_toolsets).
rate-limit.tsmcp_rate_limit on tool calls.
registry-mode.ts / type-strings.tsRegistry mode gateways; JSON Schema → TypeScript type strings.
odp-mcp.ts / routes.tsThe /mcp server and the /mcp/settings routes.
tools/*.tsThe core tools of the items, schema, files, users, access, settings, versions, activity and guide groups.

The workflow, ai and notify tools live in their own modules (see Core module tools).

POST /server/mcp (src/routes/server.ts) repeats the dispatcher steps with the module index exports (availableTools, getMCPTools, assertToolScope) and calls the tool handler itself, so it can keep its own 400 texts and { data } body.


Access Control ​

MCP is not a permission bypass. Every MCP operation runs under the caller's own access policies — exactly like the equivalent REST call. Access is enforced in two layers.

Layer 1 — Gate: who can use MCP at all ​

  1. Authenticated request — the request must carry a valid token resolving to accountability.user, accountability.role, or accountability.admin === true. Anonymous requests are rejected with 403 Forbidden (odp-mcp.ts).
  2. App permission mcp / access — when ENABLE_APP_PERMISSIONS !== 'false', the caller must be granted the app permission module = mcp, action = access via their access policy. Without it, no tool can be invoked (validateAppAccess).

Layer 2 — Per-operation: what they can see/do through MCP ​

Each core tool instantiates the matching service (ItemsService, CollectionsService, UsersService, workflow services, …) with the caller's accountability — never a system/null bypass. Because services are the only layer that touches the database and they enforce permissions internally, every MCP operation passes the full permission pipeline:

  • Collection-level — validateAccess(read | create | update | delete) throws 403 Forbidden if the policy denies the action.
  • Row-level — permission filters are merged into the query (via processAst), so the caller only sees rows their policy allows.
  • Field-level — fields the policy hides are stripped from reads and rejected on writes.

An extension tool receives the caller's accountability and must build its services with it (see Extension tools).

Implication for your team

You do not configure permissions separately for MCP. MCP inherits whatever access policies the user already has. If a user cannot read collection articles over REST, the MCP items_read tool returns the same 403 / empty result for articles. To change what an MCP user can do, edit their role / access policy — not the MCP module.

Layer 0 — Module settings (further narrowing) ​

On top of permissions, the MCP module has its own settings (managed via GET/PATCH /mcp/settings, see Configuration) that constrain everyone, including admins:

  • mcp_enabled — global on/off. When false, every /mcp and /server/mcp request returns 403 regardless of permissions (/mcp/settings stays reachable, so the module can be turned back on).
  • mcp_allowed_collections — allowlist; if set, MCP tools can only touch these collections (null = all). List tools that name no collection return only what belongs to them: schema_list, collections_list, fields_list (without collection), activity_list (plus entries of no collection, e.g. sign-ins), workflow_list (plus workflows bound to no collection), workflow_instance_list, workflow_tasks_*. workflow_instance_start with a workflow bound to no collection checks the collection it is given. versions_list requires collection and lists only its versions. What a call reaches through relations is bound too: fields, filter, sort and deep paths into another collection (ref.*, *.*, {ref: {title: …}}, children.title) and nested relational writes in data (a nested m2o row, any o2m/m2m value) are refused unless that collection (and an m2m junction) is allowed — for items_*, versions_*, users_*, roles_*, policies_*, permissions_*, files_* and activity_list. An m2o foreign key value and the keys an o2m/m2m field lists (no nested path) stay on the item and are allowed.
  • mcp_read_only_collections — collections exposed read-only through MCP even if the user's policy allows writes.
  • mcp_allow_deletes — when false, every tool whose scope deletes (scope.access = 'write', scope.deletes = true) is not exposed at all: every *_delete, *_delete_many and *_remove tool (items, access control, files, collections, fields, relations, workflows and their steps / transitions) and every extension tool that declares deletes: true.
  • mcp_toolsets — the tool groups the server serves (null = every group). See Toolsets.
  • mcp_rate_limit — tool calls per minute per caller (null = unlimited). See Rate limit.
  • mcp_default_tool_mode — the tool mode /mcp serves when a request asks none: registry or flat (null = registry). See Registry mode.

The dispatcher checks the allowlist and the read-only list for every tool before its handler runs, from the collections the tool's scope declares (tool-scope.ts). This includes extension tools. The relational checks above (queryRoot) exist on core tools only.

These narrow what MCP can do; they never widen a user's permissions. Effective access = user's access policy ∩ MCP module settings.

Setup checklist ​

To let a team member use MCP:

  1. Enable the module — set mcp_enabled = true (and optionally scope mcp_allowed_collections / mcp_read_only_collections / mcp_allow_deletes / mcp_toolsets / mcp_rate_limit / mcp_default_tool_mode) via PATCH /mcp/settings.
  2. Create a token for the user (login or a sub-token) — MCP requests authenticate with Authorization: Bearer <token>.
  3. Grant the MCP app permission — in their access policy, add module = mcp, action = access (skip only if you run with ENABLE_APP_PERMISSIONS=false, which disables Layer 1 globally — Layer 2 still applies).
  4. Grant the data permissions they need — read/create/update/delete on the specific collections, with any row filters and field restrictions. These are the same policy rules that govern REST; MCP reuses them.
User caseResult through MCP
mcp_enabled = false (module off)403 Forbidden for everyone, including admins
No token / invalid token403 Forbidden — gate rejects before any tool runs
Authenticated but no mcp / access app permission403 Forbidden — cannot invoke any tool
Has MCP access, but policy denies read on collection ABCitems_read on ABC → 403 / no rows (identical to REST)
Policy allows read on ABC with a row filterOnly the permitted rows returned; hidden fields stripped
Collection not in mcp_allowed_collectionsNot reachable via MCP even if the policy allows it
Collection in mcp_read_only_collectionsReads work; create/update/delete blocked through MCP
accountability.admin === trueBypasses auth gate + policy checks, but still bound by module settings (Layer 0)

Endpoints ​

GET /mcp · POST /mcp ​

Full MCP JSON-RPC protocol endpoint, served by OdpMCP.handleRequest(). This is the URL an MCP-compatible client (Claude, etc.) connects to — it speaks the standard MCP message protocol (initialize, tools/list, tools/call, …), not the simplified { tool, params } shape of POST /server/mcp.

Auth required: Authenticated user with the mcp / access app permission. Requests are refused with 403 Forbidden when mcp_enabled is false. The other module settings are applied per request (see Access Control).

Request options (query parameter or header; the query parameter wins):

Query parameterHeaderEffect
toolsets=items,schemax-mcp-toolsets: items,schemaServe these tool groups only, inside mcp_toolsets (Toolsets)
tool_mode=registryx-mcp-tool-mode: registryRegistry mode
tool_mode=flatx-mcp-tool-mode: flatThe flat tool list

With no tool_mode, or a value other than registry / flat, /mcp serves the mcp_default_tool_mode setting (null = registry).

A JSON-RPC notification (no id) gets no JSON-RPC response; notifications/initialized is answered with 202. A GET without a body is answered with 405.


GET /mcp/settings ​

Read the MCP module settings.

Auth required: Yes

Response 200

json
{
  "data": {
    "enabled": true,
    "allow_delete": false,
    "allowed_collections": null,
    "read_only_collections": null,
    "rate_limit": null,
    "toolsets": null,
    "default_tool_mode": "registry"
  }
}

PATCH /mcp/settings ​

Update the MCP module settings. Any subset of the fields may be sent.

Auth required: Yes

Request Body

json
{
  "enabled": true,
  "allow_delete": false,
  "allowed_collections": ["articles", "authors"],
  "read_only_collections": ["authors"],
  "rate_limit": 120,
  "toolsets": ["items", "schema"],
  "default_tool_mode": "flat"
}
FieldTypeDescription
enabledbooleanGlobal MCP on/off (mcp_enabled)
allow_deletebooleanExpose delete tools (mcp_allow_deletes)
allowed_collectionsstring[] | nullAllowlist of collections (null = all)
read_only_collectionsstring[] | nullCollections forced read-only (null = none)
rate_limitnumber | nullTool calls per minute per caller (mcp_rate_limit, null = unlimited)
toolsetsstring[] | nullTool groups served (mcp_toolsets, null = every group, [] = guide only). Each entry must be a non-empty string.
default_tool_mode"registry" | "flat" | nullTool mode of a /mcp request that asks none (mcp_default_tool_mode, null = registry). GET answers "registry" for null. Another value answers 400 ("default_tool_mode" must be "registry", "flat" or null).

A field of the wrong type answers 400 (InvalidPayloadError); a body with no known field answers 400 too. The response echoes the same shape as GET /mcp/settings.


POST /server/mcp ​

Simple tool execution endpoint (non-standard, simpler protocol).

Auth required: Admin. The MCP module settings apply as on /mcp: 403 while mcp_enabled is false, delete tools answer 400 (disabled) unless mcp_allow_deletes, mcp_allowed_collections / mcp_read_only_collections bind every tool, the mcp_toolsets setting narrows the tools (the toolsets / tool_mode request options do not apply here), and each call is charged against mcp_rate_limit. Each tool then runs under the caller's own access policies.

Request Body:

json
{
  "tool": "items_read",
  "params": {
    "collection": "articles",
    "query": { "limit": 10 }
  }
}

Response:

json
{
  "data": {
    "items": [...]
  }
}

Error responses:

CaseStatusBody
Unknown tool400{ "error": "Unknown tool: nonexistent_tool" }
Tool hidden by mcp_allow_deletes or mcp_toolsets400{ "error": "Tool \"items_delete\" is disabled on this server." }
Over mcp_rate_limit429 + Retry-After headerFastify error body with top-level code: "REQUESTS_EXCEEDED"
A 4xx error thrown by the tool (ForbiddenError, InvalidPayloadError, …)the error's statusFastify error body (statusCode, code, error, message)
An internal failure500{ "errors": [{ "message": "An unexpected error occurred", ... }] } — the raw message is not echoed

GET /server/mcp/tools ​

List every tool in the catalog with its schema, extension tools included.

Auth required: Admin.

The list is the whole catalog: it is not filtered by mcp_allow_deletes or mcp_toolsets, and it carries no title or annotations. It is not charged against mcp_rate_limit.

Response:

json
{
  "data": [
    {
      "name": "items_read",
      "description": "Read items from a user collection: ...",
      "parameters": {
        "type": "object",
        "properties": {
          "collection": { "type": "string" },
          "query": { "type": "object" }
        },
        "required": ["collection"]
      }
    }
  ]
}

Tool metadata ​

Each tool in the catalog (MCPTool, modules/mcp/types.ts) carries metadata next to its handler. The dispatcher, the toolsets and registry mode read it; tools/list derives the MCP annotations from it.

FieldMeaning
scope.access'read' or 'write'. A read tool is bound by mcp_allowed_collections; a write tool also by mcp_read_only_collections.
scope.deletesWrite tools only, required. true hides the tool while mcp_allow_deletes is off.
scope.collectionsThe collections a call touches (for a write tool: the ones it writes): a list, or a function of the arguments. The dispatcher checks them before the handler runs.
scope.readsWrite tools only, optional (core MCPToolScope; not in the extension McpToolScope). The collections a write tool only reads, same forms as collections. Checked against mcp_allowed_collections only, so a read-only collection the tool reads (a flow graph it publishes, a knowledge base a node names) does not block it.
groupThe toolset id (see Toolsets).
title, keywords, instructionsDisplay title; extra search terms for registry mode; long guidance served on demand by registry mode (odp_search({names})), never in tools/list.
destructive, openWorld, idempotentHints for the annotations below.
adminOnlyListed and callable for admins only. For anyone else the tool does not exist.

Annotations (odp-mcp.ts, toolAnnotations). Every flat tools/list entry has name, description, inputSchema, title (only when set) and annotations:

AnnotationValue
readOnlyHintscope.access === 'read'
destructiveHintwrite && (destructive ?? true) — a write tool is destructive unless it declares destructive: false
idempotentHintpresent only when the tool declares idempotent
openWorldHintopenWorld ?? false — true for users_invite (sends an email), files_import (fetches a URL) ai_knowledge_search (a RAG knowledge base calls the external KAOS search) and ai_apps_test_run (calls an LLM, HTTP and MCP tools)

Of the core tools, only the ai write tools set destructive and idempotent (see AI); every other core write tool has destructiveHint: true and no idempotentHint. Annotations are hints: clients may ignore them, and the server enforces access with scope, not with the hints.


Server instructions and odp_guide ​

The initialize response carries server instructions (tools/prompts.ts): SERVER_INSTRUCTIONS in flat mode, REGISTRY_SERVER_INSTRUCTIONS in registry mode. They tell the model to start with schema_list / schema_read, to read long references through odp_guide, and that the MCP settings can narrow what it reaches.

Tool descriptions are short. Long reference text lives in the odp_guide tool (tools/guide.ts, group guide, read-only):

  • odp_guide() lists the topics as { topic, title }.
  • odp_guide({ topic }) returns { topic, title, content }.
  • An unknown topic answers InvalidPayloadError with the list of valid topics.
TopicContent
fieldsField structure, types, special markers, conditions and validation (fields_create)
layoutForm layout: 24-column grid, width presets, groups (fields_create)
interfacesOptions of every field interface (fields_create)
filtersItems query syntax: fields, filter operators, sort, deep, functions, aggregation (items_read)

Core module topics. A core module adds topics by a static import in guide.ts, the way catalog.ts imports its tools: coreGuideTopics() = GUIDE_TOPICS, then aiGuideTopics (modules/ai/mcp-guides.ts, topics ai and ai_*, each at most 16,000 chars like an extension topic). A core module cannot use the mcp.tools registry for this: its namespace is in MCP_RESERVED_NAMESPACES.

Extensions can add guide topics with their tools (see Extension tools). The core topics come first; a registered topic with a core topic name is ignored.

odp_guide() lists every topic whatever the toolsets and the caller's permissions: each topic must make sense when read alone.


Toolsets ​

A toolset is a tool group (group on each tool). A client can ask for some groups only, and the mcp_toolsets setting can restrict the groups a server serves (toolsets.ts).

Group idTools
itemsitems_*
schemaschema_*, collections_*, fields_*, relations_*
filesfiles_*
usersusers_*
accessroles_*, policies_*, permissions_*
settingssettings_*
versionsversions_*
activityactivity_list
workflowworkflow_*
guideodp_guide
aiai_*
notifynotify_* (admin only)

An extension tool's group is its group, else its namespace. The code reserves namespaces, not groups: an extension group must not reuse one of the 12 core group names above (convention).

Rules:

  • Request — ?toolsets=items,schema or the header x-mcp-toolsets: items,schema on /mcp. The query parameter wins over the header. A value with no names (?toolsets=) is no selection.
  • Setting — mcp_toolsets (migration 099-mcp-toolsets.ts, a JSON array; null = every group).
  • The request narrows the setting, never widens it. Served groups = requested ∩ setting; with no setting, the requested groups; with no request, the setting.
  • guide, schema_list and schema_read are always served, whatever the selection: a model needs the collections and fields before it calls a data tool. The other schema tools (collections_*, fields_*, relations_*) follow the selection. mcp_toolsets = [] therefore serves odp_guide, schema_list and schema_read only.
  • A group name no tool carries matches nothing.
  • A call to a tool outside the served groups answers "disabled" on /mcp (Tool "…" is disabled on this server.) and 400 on /server/mcp.
  • POST /server/mcp applies the mcp_toolsets setting only. GET /server/mcp/tools applies no toolset.

Rate limit ​

mcp_rate_limit is the number of tool calls per minute per caller (rate-limit.ts).

  • Key — the user id, else the client IP.
  • Shared budget — /mcp tools/call and POST /server/mcp spend the same budget.
  • Charged — tools/call only. initialize, tools/list and GET /server/mcp/tools are never charged. In registry mode each gateway call (odp_search, odp_execute_read, odp_execute_write) is charged once; the tool run through an execute gateway is not charged again.
  • Unlimited — null, unset, or a value below 1.
  • Independent of RATE_LIMITER_ENABLED — that env switch gates the env-configured limiters; mcp_rate_limit is governed by the setting alone.
  • A change through PATCH /mcp/settings takes effect on the next call.
  • A refusal emits a RATE_LIMIT_TRIGGERED security event.
EndpointRefusal
/mcp (flat mode, and a catalog tool called by name in registry mode)A tool error (isError: true) with [{ "error": "Too many requests: the MCP limit is 2 tool calls per minute. Retry in 37 seconds.", "code": "REQUESTS_EXCEEDED" }]
/mcp (registry mode gateways){ "ok": false, "error": { "code": "REQUESTS_EXCEEDED", "message": "…", "recoverable": true } }
POST /server/mcp429 with a Retry-After header and code: "REQUESTS_EXCEEDED"

Registry mode ​

Registry mode keeps tools/list small for any number of tools (registry-mode.ts). It is the default of /mcp: a request that asks no mode gets registry mode unless the mcp_default_tool_mode setting is flat. ?tool_mode=registry|flat or the header x-mcp-tool-mode: registry|flat overrides the setting per request (requestedToolMode; the query parameter is checked first). Registry mode exists on /mcp only; POST /server/mcp is a plain REST route and has no tool mode.

Root tools ​

tools/list serves 6 tools:

ToolPurposeAnnotations
odp_searchDiscover and describe toolsread-only
odp_execute_readRun a tool that only readsread-only
odp_execute_writeRun any tool, including the ones that write or deletedestructive
schema_list, schema_readThe data model, listed directly because models need it firstfrom the tool
odp_guideThe guide topicsfrom the tool

schema_list, schema_read and odp_guide follow the caller's visibility and toolsets like in flat mode. Every other catalog tool, extension tools included, is not listed: the model reaches it through the gateways.

A tools/call of any catalog tool by name (for example items_read) still works, so a client written for flat mode keeps working. The call takes the flat path and answers exactly as in flat mode, with the same P9 scope, rate limit, adminOnly, mcp_allow_deletes and toolsets:

Called nameAnswer
Visible toolThe same result as in flat mode
Delete-gated, or outside the served toolsetsTool "x" is disabled on this server., as in flat mode
Not in the catalog, or admin-only for a non-admin[{ "error": "Unknown tool: \"x\". Use tools/list to see available tools. Find any other tool with odp_search; odp_guide explains how the tools work.", "suggestions": [...], "next": "odp_search({query:\"x\"})" }]

suggestions holds at most 3 visible tools, ranked by the odp_search score plus a bonus for a name word one typo away (item_read → items_read); unknownToolGuidance builds it. A hidden tool is never suggested. Flat mode keeps its unknown-tool text unchanged, without suggestions or next.

Discover → describe → execute ​

  1. Discover — odp_search({ query: "read items", limit? }) returns { results: [{ name, title?, description, access }] }, best match first. description is the first sentence of the tool description. limit defaults to 10, maximum 25. The score weighs words found in the name, the keywords, the title, the group and the description; an exact name match ranks first.
  2. Describe — odp_search({ names: ["items_read"] }) (at most 25 names) returns { tools: [{ name, title?, description, instructions?, access, deletes, inputType }], missing: [...] }. inputType is the input schema as a TypeScript type string (type-strings.ts, jsonSchemaToTypeString). A name that is not visible is in missing.
  3. Execute — odp_execute_read({ name, input }) or odp_execute_write({ name, input }). input must be an object. The call goes through the dispatcher (callTool), so the P9 scope check and the handler run exactly as in flat mode. The result is the same text result as in flat mode.

Execute rules:

  • odp_execute_read runs a tool with scope.access = 'read' only. A write tool answers WRITE_TOOL with next: "odp_execute_write".
  • odp_execute_write runs any visible tool.
  • The gateways cannot run themselves.
  • Visibility is checked before access: a hidden write tool answers UNKNOWN_TOOL, never WRITE_TOOL.

Visibility parity ​

Search and execute see exactly the tools that flat tools/list would list for the same caller and settings (availableTools). A tool that is hidden — admin-only for a non-admin, delete-gated by mcp_allow_deletes, outside the served toolsets — is not found by search and answers UNKNOWN_TOOL on execute, the same as a name that does not exist.

Errors ​

The gateway tools fail with a tool error (isError: true) whose text is:

json
{ "ok": false, "error": { "code": "UNKNOWN_TOOL", "message": "Unknown tool: \"item_read\".", "recoverable": true, "suggestions": ["items_read", "…"], "next": "odp_search({query:\"item_read\"})" } }
codeWhenrecoverablenext
UNKNOWN_TOOLName not visible or not in the catalog; also carries suggestions (at most 3 visible tools)trueodp_search({query:"<name>"})
WRITE_TOOLWrite tool sent to odp_execute_readtrueodp_execute_write
INVALID_INPUTBad gateway arguments, or the tool threw InvalidPayloadError / InvalidQueryError / FailedValidationError; non-empty extensions come back as details (see below)truethe tool's own next (see below), else odp_search({names:["<name>"]}) for a tool error; none for bad gateway arguments
FORBIDDENForbiddenError (P9 settings or access policy), or any error with status 403false—
REQUESTS_EXCEEDEDOver mcp_rate_limittrue—
the error's own codeAn error with a string code and status 400, 404, 409 or 422: a core BaseError (NotFoundError, ConflictError, MANAGED_COLLECTION…) or an extension error of the same shape (Object.assign(new Error(message), { status, code, extensions })). Non-empty extensions come back as details (see below)truethe tool's own next, else odp_search({names:["<name>"]})
the error's own codeAn error with a string code and any other status (401, 5xx…)false—
TOOL_ERRORAny other errorfalse—

details and next of a recoverable error (recoverableGuidance, both rows above):

  • details = the error's extensions without next, without unset values and without a reason that repeats the message. Left out when nothing is left.
  • next = extensions.next when it is a string that starts with odp_: a call of a root tool (odp_guide({topic: "ai_flow_edges"}), odp_execute_read({name:"ai_flow_validate", input:{…}})), optionally followed by a second step after , then (MANAGED_COLLECTION: odp_guide({topic: "ai"}), then odp_search({names:["ai_flow_add"]})). Any other value is dropped and the default stays.
  • Flat mode returns only {error, code}: a tool that sends details still lists every problem in the message.

Only the gateways use this shape. schema_list, schema_read and odp_guide keep their flat-mode errors.

When to use it ​

  • Registry mode is the default because the flat tools/list grows with every tool. Measured 2026-10-20 (admin, deletes on): flat 93 tools, 78,507 chars (~19.6k tokens); registry 6 tools, 5,080 chars plus 1,341 chars of instructions (~1.6k tokens). With 3 demo extensions the flat list is 112 tools (~23.4k tokens); registry still lists 6.
  • Use the flat mode (?tool_mode=flat, or mcp_default_tool_mode = 'flat') when the client already has tool search (for example Claude Code), so it loads tool definitions on demand itself.
  • Registry mode costs extra round-trips (search, describe, execute) per new tool.

Upgrading / restoring flat ​

  • An LLM client that reconnects to /mcp after the upgrade sees 6 tools, not the full list.
  • A client or a script that calls catalog tools by name keeps working (see Root tools).
  • A skill or prompt that tells the model to use a flat tool (for example "use items_read") must say to find it with odp_search and run it with odp_execute_read / odp_execute_write. The model does not see the flat tool in tools/list.
  • To keep the old list for everyone, set default_tool_mode to "flat" (PATCH /mcp/settings). To keep it for one client, connect with /mcp?tool_mode=flat or the header x-mcp-tool-mode: flat (see Example).

Core module tools ​

A core module that owns a feature also owns its MCP tools. The tools sit next to the module, not in modules/mcp/tools/:

ModuleFile (service/api/src/modules/)GroupTools
workflowworkflow/mcp-tools.ts (workflowMcpTools), handlers in workflow/mcp/workflow-{definitions,steps,transitions,instances,tasks}.tsworkflow25
aiai/mcp-tools.ts (aiMcpTools)ai18: 9 read, 9 write
notifynotify/mcp-tools.ts (notifyMcpTools)notify9, admin only

Rules:

  • Internal type. A module tool is an MCPTool (modules/mcp/types.ts) and receives the full MCPContext, as a core tool does. It does not go through the mcp.tools registry.
  • Order. buildTools() (catalog.ts) spreads workflowMcpTools where the workflow tools always were (after activity_list, before odp_guide). It appends aiMcpTools and then notifyMcpTools after odp_guide, so the order of the earlier tools does not change.
  • Names. Every module tool starts with a reserved namespace (workflow, ai, notify are in MCP_RESERVED_NAMESPACES), so no extension can register a tool with that name or prefix.
  • Same gate as REST. The ai and notify handlers run the same checks as their REST routes before they read or write (see below). The workflow tools were moved unchanged: they build the workflow services with the caller's accountability, and do not repeat the route-level workflow app permission check.

AI tools (ai/mcp-tools.ts). Each handler runs requireAppAccess, then gate(request, 'view' | 'manage') from ai/controllers/shared.ts, the same pair as the matching /ai/* route: view for the read tools and ai_apps_test_run (as REST chat), manage for the other write tools. gate calls validateAppAccess(accountability, 'ai', <action>): an admin passes, any other caller needs the app permission ai/<action>. Like the REST routes, this gate does not read ENABLE_APP_PERMISSIONS. The reads then go through the same svc() as REST.

Notify tools (notify/mcp-tools.ts). Every tool is adminOnly: a non-admin does not see it and a call answers "unknown tool". Each handler runs requireAdmin, then, when ENABLE_APP_PERMISSIONS is on, the same validateAppAccess(accountability, 'notify', <action>) as its route (an admin passes it; the check is logged as on REST):

ActionTools
viewnotify_templates_list, notify_template_read, notify_logs_list, notify_log_read, notify_logs_stats
testnotify_template_validate
managenotify_template_update, notify_content_create, notify_content_update

Bodies go through the route's zod schemas (notify/validation.ts). No notify tool sends, test-sends, deletes, cancels a log or touches providers, channels, layouts or settings. notify_template_validate has scope: { access: 'read' } with no collections: it only compiles a string.

Counts. getMCPTools() returns 108 tools: 81 in the core groups (workflow included, odp_guide included), 18 ai, 9 notify. An admin with mcp_allow_deletes on sees all 108 in flat tools/list (92,278 chars). A non-admin sees at most 99 (no notify tools). mcp_allow_deletes off hides the 14 delete tools (12 core + ai_flow_remove, ai_apps_delete).

To add MCP tools to a backend extension, use the mcp.tools registry below and the skill .claude/skills/odp-backend-ext-mcp/.


Extension tools ​

An extension adds MCP tools through the mcp.tools service ref (mcpToolsRef). The core provides it before extensions.register (src/index.ts, provideMcpRegistry); an extension consumes it in init('app.before'):

ts
import { defineHook, mcpToolsRef } from '@odp/extensions-sdk';

export default defineHook(({ init }, { registry, services, database }) => {
  init('app.before', () => {
    registry.tryConsume(mcpToolsRef)?.register({
      namespace: 'projects',
      tools: [{
        name: 'projects_list',
        description: 'List projects the caller can read.',
        group: 'projects',
        scope: { access: 'read', collections: ['projects'] },
        inputSchema: { type: 'object', properties: { limit: { type: 'number' } } },
        handler: async (args, { accountability, schema }) => {
          const service = new services.ItemsService('projects', { knex: database, accountability, schema });
          return service.readByQuery({ limit: (args.limit as number) ?? 20 });
        },
      }],
    });
  });
});

What the core does with them:

  • Registered tools are served after the core tools (core module tools included), in flat tools/list, registry mode, POST /server/mcp and GET /server/mcp/tools.
  • The dispatcher applies the same rules as to core tools: scope.collections against the allowlist / read-only list, deletes: true against mcp_allow_deletes, adminOnly, toolsets.
  • The handler receives { accountability, schema, logger } only — no knex, no MCP settings — and must enforce the same access as the equivalent REST route.

The full contract (naming, reserved namespaces, limits, required scope, re-register and deregister) is in Extension Guardrails §6 — MCP tools từ extension.


Available Tools ​

The group id after each heading is the toolset id for ?toolsets=.

Items (items) ​

ToolDescription
items_readRead items from a collection with optional query
items_createCreate a single item
items_updateUpdate a single item by ID
items_deleteDelete a single item
items_create_manyCreate multiple items
items_update_manyUpdate multiple items
items_delete_manyDelete multiple items

Module collections (tools/managed-collections.ts). The items_* write tools refuse the collections a core module writes through its own tools, also when the payload reaches one through a relation (collectionsWrittenByData). Reads stay open. The refusal is a 400 MANAGED_COLLECTION error, recoverable in registry mode, whose message, details (collection, tool, guide) and next name the module tool and its guide topic. Each write tool's instructions list the rule. REST /items and import are not covered.

CollectioncreateupdatedeleteGuide
ai_appsai_apps_createai_apps_updateai_apps_deleteai
ai_flow_nodes, ai_flow_edgesai_flow_addai_flow_updateai_flow_removeai

Schema (schema) ​

ToolDescription
schema_listList all collections with their fields
schema_readRead schema for a specific collection

Collections (schema) ​

ToolDescription
collections_createCreate a new collection
collections_listList all collections
collections_readRead a collection's metadata
collections_updateUpdate a collection's metadata
collections_deleteDelete a collection

Fields (schema) ​

ToolDescription
fields_listList fields for a collection (or all collections)
fields_readRead full metadata for a single field
fields_createAdd a field to a collection
fields_updateUpdate a field's configuration
fields_deleteRemove a field from a collection

Relations (schema) ​

ToolDescription
relations_createCreate a relation between collections
relations_listList all relations
relations_readRead a specific relation
relations_updateUpdate a relation
relations_deleteDelete a relation

Files (files) ​

ToolDescription
files_listList files with optional filters
files_readRead a file's metadata by ID
files_importImport a file into storage from a public http(s) URL
files_updateUpdate a file's metadata (does not change the binary)
files_deleteDelete a file (record + stored binary). Irreversible

Users (users) ​

ToolDescription
users_listList users
users_readRead a user by ID
users_createCreate a user
users_updateUpdate a user by ID (also used to deactivate via status)
users_inviteInvite a user by email to a role

Roles (access) ​

ToolDescription
roles_listList roles
roles_readRead a role by ID
roles_createCreate a role
roles_updateUpdate a role by ID
roles_deleteDelete a role by ID. Irreversible

Policies (access) ​

ToolDescription
policies_listList access policies
policies_readRead an access policy by ID
policies_createCreate an access policy
policies_updateUpdate an access policy by ID
policies_deleteDelete an access policy by ID. Irreversible

Permissions (access) ​

ToolDescription
permissions_listList permission rules
permissions_readRead a permission rule by ID
permissions_createCreate a permission rule
permissions_updateUpdate a permission rule by ID
permissions_deleteDelete a permission rule by ID. Irreversible

Settings (settings) ​

ToolDescription
settings_readRead the global project settings singleton
settings_updateUpdate the global project settings singleton

Versions (versions) ​

ToolDescription
versions_listList content versions
versions_readRead a version by ID
versions_promotePromote a version to live content

Activity (activity) ​

ToolDescription
activity_listQuery activity log

Workflow (Definition) (workflow) ​

ToolDescription
workflow_createCreate a workflow definition
workflow_listList workflow definitions
workflow_readRead a workflow
workflow_updateUpdate a workflow
workflow_deleteDelete a workflow
workflow_duplicateDuplicate a workflow
workflow_activateActivate a workflow
workflow_deactivateDeactivate a workflow

Workflow Steps & Transitions (workflow) ​

ToolDescription
workflow_step_addAdd a step to a workflow
workflow_step_updateUpdate a step
workflow_step_removeRemove a step
workflow_transition_addAdd a transition between steps
workflow_transition_updateUpdate a transition
workflow_transition_removeRemove a transition

Workflow Instances (workflow) ​

ToolDescription
workflow_instance_startStart a workflow instance
workflow_instance_listList instances
workflow_instance_readRead an instance
workflow_instance_cancelCancel an instance
workflow_instance_approveApprove a step
workflow_instance_rejectReject a step
workflow_instance_delegateDelegate a step to another user
workflow_instance_commentAdd a comment to an instance

Workflow Tasks (workflow) ​

ToolDescription
workflow_tasks_mineGet tasks assigned to current user
workflow_tasks_allGet all pending tasks
workflow_tasks_countCount pending tasks

Guide (guide) ​

ToolDescription
odp_guideList the reference topics, or read one (see odp_guide)

AI (ai) ​

Read tools need the app permission ai/view; write tools ai/manage, except ai_apps_test_run (ai/view, as REST chat). See Core module tools.

ToolDescription
ai_apps_listList AI apps (no config, no flow graph)
ai_knowledge_listList knowledge bases (source_config masked)
ai_knowledge_searchRun a retrieval test against one knowledge base; each hit's content is cut to 1,500 characters
ai_apps_readOne app: fields, config, flow graph {nodes, edges} and its current problems; secret-looking node data masked
ai_flow_node_typesThe flow graph node types with their handles; with {type}, its data schema, defaults, example and guide topic
ai_flow_validateCheck the stored graph of an app, or a proposed {nodes, edges}, without saving; {valid, publishable, problems}
ai_models_listEnabled model integrations and their models (no base URL, no key)
ai_mcp_servers_listMCP servers an mcp-agent node can call, with their stored tool names (no URL, no headers, no connection)
ai_skills_listAgent skills with their category, without the body

Write tools. destructive: false on all but the two delete tools; deletes: true hides them while mcp_allow_deletes is off.

ToolGateWrites (collections)Only reads (reads)Hints
ai_apps_createmanageai_apps, ai_flow_nodes—
ai_apps_updatemanageai_apps—idempotent
ai_flow_addmanageai_flow_nodes, ai_flow_edgesai_apps + references of the graph after the write
ai_flow_updatemanageai_flow_nodes, ai_flow_edgesai_apps + references of the graph after the writeidempotent
ai_flow_removemanageai_flow_nodes, ai_flow_edgesai_apps + references of the stored graphdeletes, destructive
ai_apps_publishmanageai_appsai_flow_nodes, ai_flow_edges + references
ai_apps_clonemanageai_apps, ai_flow_nodes, ai_flow_edges—
ai_apps_deletemanageai_apps, ai_flow_nodes, ai_flow_edges—deletes, destructive
ai_apps_test_runview—graph tables, ai_integrations, references, a collection-kind KB's rows, ai_mcp_servers / ai_skills when usedopen world

A graph write that adds or changes a code node is refused for a non-admin (ForbiddenError).

ai_apps_read and ai_flow_validate scope the graph tables plus the reference tables (knowledge bases, integrations, MCP servers, skills) the graph's nodes use. The ai guide topics (ai, ai_flow_*) explain the build loop. Contract: .cos/features/ai/ai-flow-mcp-contract.md.

Notify (notify) ​

Admin only (see Core module tools).

ToolDescription
notify_templates_listList notification templates (no contents)
notify_template_readRead a template with its contents
notify_template_validateCheck a Handlebars string; renders, sends and saves nothing
notify_logs_listList delivery logs, newest first; filter by status, template, recipient, date range (no rendered body)
notify_log_readRead one delivery log in full (credential variables masked)
notify_logs_statsCount of delivery logs per status, and the total
notify_template_updateUpdate a template
notify_content_createAdd a content (provider + locale) to a template
notify_content_updateUpdate a template content

OdpMCP Configuration ​

The OdpMCP class accepts an allowDeletes option:

typescript
const mcp = new OdpMCP({ allowDeletes: false });

When allowDeletes = false (default), every tool whose scope deletes is excluded from the tool list and refused on call. routes.ts keeps one OdpMCP instance per mcp_allow_deletes value. An instance holds no tool list: it reads the catalog on each request, and the other settings (toolsets, rateLimit, defaultToolMode, collection scopes) are passed to handleRequest() per request.


MCPContext ​

Each core tool handler receives a context object:

typescript
interface MCPContext {
  knex: Knex;               // Database connection
  accountability: Accountability | null;  // Caller's permissions
  schema: SchemaOverview;   // Current database schema
  settings: MCPSettings;    // Collection access settings
}

interface MCPSettings {
  allowedCollections: string[] | null;  // null = all collections
  readOnlyCollections: string[] | null; // null = none read-only
}

An extension tool handler receives McpToolContext instead: { accountability, schema, logger } (src/types/extensions.ts).

NOTE

mcp_enabled, mcp_allow_deletes, mcp_toolsets, mcp_rate_limit and mcp_default_tool_mode are stored alongside the collection scopes as module settings (see /mcp/settings). loadMCPConfig() (routes.ts) reads them for every MCP entry point: enabled gates the request, allow_delete selects the OdpMCP instance, default_tool_mode is the mode of a /mcp request that asks none, and allowedCollections / readOnlyCollections are passed into the per-request MCPSettings above.


Example: Using MCP with Claude ​

json
{
  "mcpServers": {
    "odp": {
      "url": "https://api.example.com/api/mcp",
      "headers": {
        "Authorization": "Bearer <access_token>"
      }
    }
  }
}

This connects in registry mode (the default). Then in Claude:

Get the latest 5 published articles from the "articles" collection.

The model finds items_read with odp_search and runs it with odp_execute_read.

To serve only some groups, or the flat list, add the request options to the URL or the headers:

json
{
  "mcpServers": {
    "odp-content": {
      "url": "https://api.example.com/api/mcp?toolsets=items,schema",
      "headers": { "Authorization": "Bearer <access_token>" }
    },
    "odp-flat": {
      "url": "https://api.example.com/api/mcp?tool_mode=flat",
      "headers": { "Authorization": "Bearer <access_token>" }
    }
  }
}

Configuration ​

VariableDefaultDescription
ENABLE_APP_PERMISSIONStrueSet to false to disable app permission checks

The module settings are columns of the settings singleton (odp_settings), read through SettingsService:

ColumnAPI fieldDefaultDescription
mcp_enabledenabledoffGlobal MCP on/off
mcp_allow_deletesallow_deleteoffExpose delete tools
mcp_allowed_collectionsallowed_collectionsnull (all)Allowlist of collections (JSON array)
mcp_read_only_collectionsread_only_collectionsnull (none)Collections forced read-only (JSON array)
mcp_rate_limitrate_limitnull (unlimited)Tool calls per minute per caller
mcp_toolsetstoolsetsnull (every group)Tool groups served (JSON array); guide, schema_list and schema_read are always served
mcp_default_tool_modedefault_tool_modenull (registry)Tool mode of a /mcp request that asks none: registry or flat (migration 100-mcp-default-tool-mode.ts)

ODP Internal API Documentation