Appearance
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.ts | McpCatalog: 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.ts | availableTools() (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.ts | assertToolScope() (P9 collection checks from each tool's scope) and deletesData() (delete gating). |
registry.ts / provide.ts | The mcp.tools registry and its service-registry facade. |
toolsets.ts | Tool groups (?toolsets=, x-mcp-toolsets, mcp_toolsets). |
rate-limit.ts | mcp_rate_limit on tool calls. |
registry-mode.ts / type-strings.ts | Registry mode gateways; JSON Schema → TypeScript type strings. |
odp-mcp.ts / routes.ts | The /mcp server and the /mcp/settings routes. |
tools/*.ts | The 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
- Authenticated request — the request must carry a valid token resolving to
accountability.user,accountability.role, oraccountability.admin === true. Anonymous requests are rejected with403 Forbidden(odp-mcp.ts). - App permission
mcp / access— whenENABLE_APP_PERMISSIONS !== 'false', the caller must be granted the app permissionmodule = mcp, action = accessvia 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)throws403 Forbiddenif 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. Whenfalse, every/mcpand/server/mcprequest returns403regardless of permissions (/mcp/settingsstays 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(withoutcollection),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_startwith a workflow bound to no collection checks thecollectionit is given.versions_listrequirescollectionand lists only its versions. What a call reaches through relations is bound too:fields,filter,sortanddeeppaths into another collection (ref.*,*.*,{ref: {title: …}},children.title) and nested relational writes indata(a nested m2o row, any o2m/m2m value) are refused unless that collection (and an m2m junction) is allowed — foritems_*,versions_*,users_*,roles_*,policies_*,permissions_*,files_*andactivity_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— whenfalse, every tool whose scope deletes (scope.access = 'write',scope.deletes = true) is not exposed at all: every*_delete,*_delete_manyand*_removetool (items, access control, files, collections, fields, relations, workflows and their steps / transitions) and every extension tool that declaresdeletes: 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/mcpserves when a request asks none:registryorflat(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:
- Enable the module — set
mcp_enabled = true(and optionally scopemcp_allowed_collections/mcp_read_only_collections/mcp_allow_deletes/mcp_toolsets/mcp_rate_limit/mcp_default_tool_mode) viaPATCH /mcp/settings. - Create a token for the user (login or a sub-token) — MCP requests authenticate with
Authorization: Bearer <token>. - Grant the MCP app permission — in their access policy, add
module = mcp, action = access(skip only if you run withENABLE_APP_PERMISSIONS=false, which disables Layer 1 globally — Layer 2 still applies). - 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 case | Result through MCP |
|---|---|
mcp_enabled = false (module off) | 403 Forbidden for everyone, including admins |
| No token / invalid token | 403 Forbidden — gate rejects before any tool runs |
Authenticated but no mcp / access app permission | 403 Forbidden — cannot invoke any tool |
Has MCP access, but policy denies read on collection ABC | items_read on ABC → 403 / no rows (identical to REST) |
Policy allows read on ABC with a row filter | Only the permitted rows returned; hidden fields stripped |
Collection not in mcp_allowed_collections | Not reachable via MCP even if the policy allows it |
Collection in mcp_read_only_collections | Reads work; create/update/delete blocked through MCP |
accountability.admin === true | Bypasses 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 parameter | Header | Effect |
|---|---|---|
toolsets=items,schema | x-mcp-toolsets: items,schema | Serve these tool groups only, inside mcp_toolsets (Toolsets) |
tool_mode=registry | x-mcp-tool-mode: registry | Registry mode |
tool_mode=flat | x-mcp-tool-mode: flat | The 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"
}| Field | Type | Description |
|---|---|---|
enabled | boolean | Global MCP on/off (mcp_enabled) |
allow_delete | boolean | Expose delete tools (mcp_allow_deletes) |
allowed_collections | string[] | null | Allowlist of collections (null = all) |
read_only_collections | string[] | null | Collections forced read-only (null = none) |
rate_limit | number | null | Tool calls per minute per caller (mcp_rate_limit, null = unlimited) |
toolsets | string[] | null | Tool groups served (mcp_toolsets, null = every group, [] = guide only). Each entry must be a non-empty string. |
default_tool_mode | "registry" | "flat" | null | Tool 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:
| Case | Status | Body |
|---|---|---|
| Unknown tool | 400 | { "error": "Unknown tool: nonexistent_tool" } |
Tool hidden by mcp_allow_deletes or mcp_toolsets | 400 | { "error": "Tool \"items_delete\" is disabled on this server." } |
Over mcp_rate_limit | 429 + Retry-After header | Fastify error body with top-level code: "REQUESTS_EXCEEDED" |
A 4xx error thrown by the tool (ForbiddenError, InvalidPayloadError, …) | the error's status | Fastify error body (statusCode, code, error, message) |
| An internal failure | 500 | { "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.
| Field | Meaning |
|---|---|
scope.access | 'read' or 'write'. A read tool is bound by mcp_allowed_collections; a write tool also by mcp_read_only_collections. |
scope.deletes | Write tools only, required. true hides the tool while mcp_allow_deletes is off. |
scope.collections | The 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.reads | Write 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. |
group | The toolset id (see Toolsets). |
title, keywords, instructions | Display title; extra search terms for registry mode; long guidance served on demand by registry mode (odp_search({names})), never in tools/list. |
destructive, openWorld, idempotent | Hints for the annotations below. |
adminOnly | Listed 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:
| Annotation | Value |
|---|---|
readOnlyHint | scope.access === 'read' |
destructiveHint | write && (destructive ?? true) — a write tool is destructive unless it declares destructive: false |
idempotentHint | present only when the tool declares idempotent |
openWorldHint | openWorld ?? 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
InvalidPayloadErrorwith the list of valid topics.
| Topic | Content |
|---|---|
fields | Field structure, types, special markers, conditions and validation (fields_create) |
layout | Form layout: 24-column grid, width presets, groups (fields_create) |
interfaces | Options of every field interface (fields_create) |
filters | Items 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 id | Tools |
|---|---|
items | items_* |
schema | schema_*, collections_*, fields_*, relations_* |
files | files_* |
users | users_* |
access | roles_*, policies_*, permissions_* |
settings | settings_* |
versions | versions_* |
activity | activity_list |
workflow | workflow_* |
guide | odp_guide |
ai | ai_* |
notify | notify_* (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,schemaor the headerx-mcp-toolsets: items,schemaon/mcp. The query parameter wins over the header. A value with no names (?toolsets=) is no selection. - Setting —
mcp_toolsets(migration099-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_listandschema_readare always served, whatever the selection: a model needs the collections and fields before it calls a data tool. The otherschematools (collections_*,fields_*,relations_*) follow the selection.mcp_toolsets = []therefore servesodp_guide,schema_listandschema_readonly.- 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.) and400on/server/mcp. POST /server/mcpapplies themcp_toolsetssetting only.GET /server/mcp/toolsapplies 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 —
/mcptools/callandPOST /server/mcpspend the same budget. - Charged —
tools/callonly.initialize,tools/listandGET /server/mcp/toolsare 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_limitis governed by the setting alone. - A change through
PATCH /mcp/settingstakes effect on the next call. - A refusal emits a
RATE_LIMIT_TRIGGEREDsecurity event.
| Endpoint | Refusal |
|---|---|
/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/mcp | 429 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:
| Tool | Purpose | Annotations |
|---|---|---|
odp_search | Discover and describe tools | read-only |
odp_execute_read | Run a tool that only reads | read-only |
odp_execute_write | Run any tool, including the ones that write or delete | destructive |
schema_list, schema_read | The data model, listed directly because models need it first | from the tool |
odp_guide | The guide topics | from 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 name | Answer |
|---|---|
| Visible tool | The same result as in flat mode |
| Delete-gated, or outside the served toolsets | Tool "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
- Discover —
odp_search({ query: "read items", limit? })returns{ results: [{ name, title?, description, access }] }, best match first.descriptionis the first sentence of the tool description.limitdefaults to 10, maximum 25. The score weighs words found in the name, thekeywords, the title, the group and the description; an exact name match ranks first. - Describe —
odp_search({ names: ["items_read"] })(at most 25 names) returns{ tools: [{ name, title?, description, instructions?, access, deletes, inputType }], missing: [...] }.inputTypeis the input schema as a TypeScript type string (type-strings.ts,jsonSchemaToTypeString). A name that is not visible is inmissing. - Execute —
odp_execute_read({ name, input })orodp_execute_write({ name, input }).inputmust 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_readruns a tool withscope.access = 'read'only. A write tool answersWRITE_TOOLwithnext: "odp_execute_write".odp_execute_writeruns any visible tool.- The gateways cannot run themselves.
- Visibility is checked before access: a hidden write tool answers
UNKNOWN_TOOL, neverWRITE_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\"})" } }code | When | recoverable | next |
|---|---|---|---|
UNKNOWN_TOOL | Name not visible or not in the catalog; also carries suggestions (at most 3 visible tools) | true | odp_search({query:"<name>"}) |
WRITE_TOOL | Write tool sent to odp_execute_read | true | odp_execute_write |
INVALID_INPUT | Bad gateway arguments, or the tool threw InvalidPayloadError / InvalidQueryError / FailedValidationError; non-empty extensions come back as details (see below) | true | the tool's own next (see below), else odp_search({names:["<name>"]}) for a tool error; none for bad gateway arguments |
FORBIDDEN | ForbiddenError (P9 settings or access policy), or any error with status 403 | false | — |
REQUESTS_EXCEEDED | Over mcp_rate_limit | true | — |
| the error's own code | An 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) | true | the tool's own next, else odp_search({names:["<name>"]}) |
| the error's own code | An error with a string code and any other status (401, 5xx…) | false | — |
TOOL_ERROR | Any other error | false | — |
details and next of a recoverable error (recoverableGuidance, both rows above):
details= the error'sextensionswithoutnext, without unset values and without areasonthat repeats the message. Left out when nothing is left.next=extensions.nextwhen it is a string that starts withodp_: 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 sendsdetailsstill 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, ormcp_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
/mcpafter 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 withodp_searchand run it withodp_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_modeto"flat"(PATCH /mcp/settings). To keep it for one client, connect with/mcp?tool_mode=flator the headerx-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/:
| Module | File (service/api/src/modules/) | Group | Tools |
|---|---|---|---|
| workflow | workflow/mcp-tools.ts (workflowMcpTools), handlers in workflow/mcp/workflow-{definitions,steps,transitions,instances,tasks}.ts | workflow | 25 |
| ai | ai/mcp-tools.ts (aiMcpTools) | ai | 18: 9 read, 9 write |
| notify | notify/mcp-tools.ts (notifyMcpTools) | notify | 9, admin only |
Rules:
- Internal type. A module tool is an
MCPTool(modules/mcp/types.ts) and receives the fullMCPContext, as a core tool does. It does not go through themcp.toolsregistry. - Order.
buildTools()(catalog.ts) spreadsworkflowMcpToolswhere the workflow tools always were (afteractivity_list, beforeodp_guide). It appendsaiMcpToolsand thennotifyMcpToolsafterodp_guide, so the order of the earlier tools does not change. - Names. Every module tool starts with a reserved namespace (
workflow,ai,notifyare inMCP_RESERVED_NAMESPACES), so no extension can register a tool with that name or prefix. - Same gate as REST. The
aiandnotifyhandlers run the same checks as their REST routes before they read or write (see below). Theworkflowtools were moved unchanged: they build the workflow services with the caller's accountability, and do not repeat the route-levelworkflowapp 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):
| Action | Tools |
|---|---|
view | notify_templates_list, notify_template_read, notify_logs_list, notify_log_read, notify_logs_stats |
test | notify_template_validate |
manage | notify_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/mcpandGET /server/mcp/tools. - The dispatcher applies the same rules as to core tools:
scope.collectionsagainst the allowlist / read-only list,deletes: trueagainstmcp_allow_deletes,adminOnly, toolsets. - The handler receives
{ accountability, schema, logger }only — noknex, 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)
| Tool | Description |
|---|---|
items_read | Read items from a collection with optional query |
items_create | Create a single item |
items_update | Update a single item by ID |
items_delete | Delete a single item |
items_create_many | Create multiple items |
items_update_many | Update multiple items |
items_delete_many | Delete 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.
| Collection | create | update | delete | Guide |
|---|---|---|---|---|
ai_apps | ai_apps_create | ai_apps_update | ai_apps_delete | ai |
ai_flow_nodes, ai_flow_edges | ai_flow_add | ai_flow_update | ai_flow_remove | ai |
Schema (schema)
| Tool | Description |
|---|---|
schema_list | List all collections with their fields |
schema_read | Read schema for a specific collection |
Collections (schema)
| Tool | Description |
|---|---|
collections_create | Create a new collection |
collections_list | List all collections |
collections_read | Read a collection's metadata |
collections_update | Update a collection's metadata |
collections_delete | Delete a collection |
Fields (schema)
| Tool | Description |
|---|---|
fields_list | List fields for a collection (or all collections) |
fields_read | Read full metadata for a single field |
fields_create | Add a field to a collection |
fields_update | Update a field's configuration |
fields_delete | Remove a field from a collection |
Relations (schema)
| Tool | Description |
|---|---|
relations_create | Create a relation between collections |
relations_list | List all relations |
relations_read | Read a specific relation |
relations_update | Update a relation |
relations_delete | Delete a relation |
Files (files)
| Tool | Description |
|---|---|
files_list | List files with optional filters |
files_read | Read a file's metadata by ID |
files_import | Import a file into storage from a public http(s) URL |
files_update | Update a file's metadata (does not change the binary) |
files_delete | Delete a file (record + stored binary). Irreversible |
Users (users)
| Tool | Description |
|---|---|
users_list | List users |
users_read | Read a user by ID |
users_create | Create a user |
users_update | Update a user by ID (also used to deactivate via status) |
users_invite | Invite a user by email to a role |
Roles (access)
| Tool | Description |
|---|---|
roles_list | List roles |
roles_read | Read a role by ID |
roles_create | Create a role |
roles_update | Update a role by ID |
roles_delete | Delete a role by ID. Irreversible |
Policies (access)
| Tool | Description |
|---|---|
policies_list | List access policies |
policies_read | Read an access policy by ID |
policies_create | Create an access policy |
policies_update | Update an access policy by ID |
policies_delete | Delete an access policy by ID. Irreversible |
Permissions (access)
| Tool | Description |
|---|---|
permissions_list | List permission rules |
permissions_read | Read a permission rule by ID |
permissions_create | Create a permission rule |
permissions_update | Update a permission rule by ID |
permissions_delete | Delete a permission rule by ID. Irreversible |
Settings (settings)
| Tool | Description |
|---|---|
settings_read | Read the global project settings singleton |
settings_update | Update the global project settings singleton |
Versions (versions)
| Tool | Description |
|---|---|
versions_list | List content versions |
versions_read | Read a version by ID |
versions_promote | Promote a version to live content |
Activity (activity)
| Tool | Description |
|---|---|
activity_list | Query activity log |
Workflow (Definition) (workflow)
| Tool | Description |
|---|---|
workflow_create | Create a workflow definition |
workflow_list | List workflow definitions |
workflow_read | Read a workflow |
workflow_update | Update a workflow |
workflow_delete | Delete a workflow |
workflow_duplicate | Duplicate a workflow |
workflow_activate | Activate a workflow |
workflow_deactivate | Deactivate a workflow |
Workflow Steps & Transitions (workflow)
| Tool | Description |
|---|---|
workflow_step_add | Add a step to a workflow |
workflow_step_update | Update a step |
workflow_step_remove | Remove a step |
workflow_transition_add | Add a transition between steps |
workflow_transition_update | Update a transition |
workflow_transition_remove | Remove a transition |
Workflow Instances (workflow)
| Tool | Description |
|---|---|
workflow_instance_start | Start a workflow instance |
workflow_instance_list | List instances |
workflow_instance_read | Read an instance |
workflow_instance_cancel | Cancel an instance |
workflow_instance_approve | Approve a step |
workflow_instance_reject | Reject a step |
workflow_instance_delegate | Delegate a step to another user |
workflow_instance_comment | Add a comment to an instance |
Workflow Tasks (workflow)
| Tool | Description |
|---|---|
workflow_tasks_mine | Get tasks assigned to current user |
workflow_tasks_all | Get all pending tasks |
workflow_tasks_count | Count pending tasks |
Guide (guide)
| Tool | Description |
|---|---|
odp_guide | List 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.
| Tool | Description |
|---|---|
ai_apps_list | List AI apps (no config, no flow graph) |
ai_knowledge_list | List knowledge bases (source_config masked) |
ai_knowledge_search | Run a retrieval test against one knowledge base; each hit's content is cut to 1,500 characters |
ai_apps_read | One app: fields, config, flow graph {nodes, edges} and its current problems; secret-looking node data masked |
ai_flow_node_types | The flow graph node types with their handles; with {type}, its data schema, defaults, example and guide topic |
ai_flow_validate | Check the stored graph of an app, or a proposed {nodes, edges}, without saving; {valid, publishable, problems} |
ai_models_list | Enabled model integrations and their models (no base URL, no key) |
ai_mcp_servers_list | MCP servers an mcp-agent node can call, with their stored tool names (no URL, no headers, no connection) |
ai_skills_list | Agent 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.
| Tool | Gate | Writes (collections) | Only reads (reads) | Hints |
|---|---|---|---|---|
ai_apps_create | manage | ai_apps, ai_flow_nodes | — | |
ai_apps_update | manage | ai_apps | — | idempotent |
ai_flow_add | manage | ai_flow_nodes, ai_flow_edges | ai_apps + references of the graph after the write | |
ai_flow_update | manage | ai_flow_nodes, ai_flow_edges | ai_apps + references of the graph after the write | idempotent |
ai_flow_remove | manage | ai_flow_nodes, ai_flow_edges | ai_apps + references of the stored graph | deletes, destructive |
ai_apps_publish | manage | ai_apps | ai_flow_nodes, ai_flow_edges + references | |
ai_apps_clone | manage | ai_apps, ai_flow_nodes, ai_flow_edges | — | |
ai_apps_delete | manage | ai_apps, ai_flow_nodes, ai_flow_edges | — | deletes, destructive |
ai_apps_test_run | view | — | graph tables, ai_integrations, references, a collection-kind KB's rows, ai_mcp_servers / ai_skills when used | open 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).
| Tool | Description |
|---|---|
notify_templates_list | List notification templates (no contents) |
notify_template_read | Read a template with its contents |
notify_template_validate | Check a Handlebars string; renders, sends and saves nothing |
notify_logs_list | List delivery logs, newest first; filter by status, template, recipient, date range (no rendered body) |
notify_log_read | Read one delivery log in full (credential variables masked) |
notify_logs_stats | Count of delivery logs per status, and the total |
notify_template_update | Update a template |
notify_content_create | Add a content (provider + locale) to a template |
notify_content_update | Update 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
| Variable | Default | Description |
|---|---|---|
ENABLE_APP_PERMISSIONS | true | Set to false to disable app permission checks |
The module settings are columns of the settings singleton (odp_settings), read through SettingsService:
| Column | API field | Default | Description |
|---|---|---|---|
mcp_enabled | enabled | off | Global MCP on/off |
mcp_allow_deletes | allow_delete | off | Expose delete tools |
mcp_allowed_collections | allowed_collections | null (all) | Allowlist of collections (JSON array) |
mcp_read_only_collections | read_only_collections | null (none) | Collections forced read-only (JSON array) |
mcp_rate_limit | rate_limit | null (unlimited) | Tool calls per minute per caller |
mcp_toolsets | toolsets | null (every group) | Tool groups served (JSON array); guide, schema_list and schema_read are always served |
mcp_default_tool_mode | default_tool_mode | null (registry) | Tool mode of a /mcp request that asks none: registry or flat (migration 100-mcp-default-tool-mode.ts) |