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, workflow operations) as typed tools that can be discovered and called by any MCP-compatible AI client (Claude, ChatGPT plugins, etc.).

---

Architecture

ODP implements MCP in two modes:

1. Stateless HTTP (per-request)

POST /server/mcp — A simple endpoint where each request is handled by a fresh MCP Server instance and FastifyTransport. No persistent connection required.

2. Full MCP Protocol (via OdpMCP)

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.

---

Access Control

MCP access requires:

1. An authenticated request (accountability.user or accountability.admin)
2. If ENABLE_APP_PERMISSIONS !== 'false': the user must have app permission module = mcp, action = access

---

Endpoints

POST /server/mcp

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

Auth required: Admin access

Request Body:

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

Response:

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

Error response:

{
  "error": "Unknown tool: nonexistent_tool"
}

---

GET /server/mcp/tools

List all available MCP tools with their schemas.

Auth required: Admin access

Response:

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

---

Available Tools

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

Schema

Tool	Description
schema_list	List all collections with their fields
schema_read	Read schema for a specific collection

Collections

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

Tool	Description
fields_create	Add a field to a collection
fields_update	Update a field's configuration
fields_delete	Remove a field from a collection

Relations

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

Tool	Description
files_list	List files with optional filters
files_read	Read a file's metadata by ID

Users

Tool	Description
users_list	List users
users_read	Read a user by ID

Versions

Tool	Description
versions_list	List content versions
versions_read	Read a version by ID
versions_promote	Promote a version to live content

Activity

Tool	Description
activity_list	Query activity log

Workflow (Definition)

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

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

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

Tool	Description
workflow_tasks_mine	Get tasks assigned to current user
workflow_tasks_all	Get all pending tasks
workflow_tasks_count	Count pending tasks

---

OdpMCP Configuration

The OdpMCP class accepts an allowDeletes option:

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

When allowDeletes = false (default), items_delete and items_delete_many tools are excluded from the tool list. This provides a safety guard for production MCP deployments.

---

MCPContext

Each tool handler receives a context object:

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
}

---

Example: Using MCP with Claude

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

Then in Claude:

Use the items_read tool to get the latest 5 published articles from the "articles" collection.

---

Configuration

Variable	Default	Description
ENABLE_APP_PERMISSIONS	true	Set to false to disable app permission checks

MCP settings are also stored in odp_extension_settings with key system_mcp_settings and can include allowedCollections and readOnlyCollections lists.