MCP Integration

oCore implements a Model Context Protocol (MCP) server that lets AI assistants interact with your Odoo instances directly. MCP is an open standard that provides a structured way for AI tools to discover and call functions exposed by external systems. Through oCore's MCP server, assistants like Claude Desktop, Cursor, and other MCP-compatible clients can search records, inspect schemas, run SQL queries, manage modules, and more -- all scoped to the instances your API key has access to.

How It Works

When an AI assistant connects to oCore's MCP server, it authenticates with an API key and receives a list of tools namespaced by instance. For example, if your API key has access to an instance with slug prod-v17, the assistant sees tools like prod_v17_search_read, prod_v17_execute_sql, and prod_v17_list_models. The assistant can then call these tools as part of a conversation to read data, inspect schemas, or perform operations on that Odoo instance.

Each MCP session is isolated: the tools available depend on the API key's permissions, instance scoping, and your organization's security settings.

Setting Up MCP Access

There are two ways to connect an AI assistant to oCore:

1. OAuth flow (recommended): The AI client connects directly using the MCP server URL. oCore handles authentication through an OAuth consent screen in your browser -- no API key copying required.
2. Manual API key: Create an API key in the dashboard and paste it into the client's configuration file.

Connecting Claude Desktop

Claude Desktop supports OAuth-based MCP connections. Add this to your claude_desktop_config.json (typically at ~/.config/claude/claude_desktop_config.json on Linux or ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "ocore": {
      "type": "sse",
      "url": "https://your-ocore-domain.com/api/mcp/sse"
    }
  }
}

{
  "mcpServers": {
    "ocore": {
      "type": "sse",
      "url": "https://your-ocore-domain.com/api/mcp/sse",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

After saving the config, restart Claude Desktop. The MCP tools will appear in the tool picker.

Connecting ChatGPT

ChatGPT uses the same OAuth-based MCP connection flow. When you add oCore as an MCP server in ChatGPT:

The OAuth Consent Flow

When an AI client initiates an OAuth connection, you will see a consent screen in your browser. This is what happens:

Managing OAuth Authorizations

Navigate to Settings > OAuth Authorizations to view and manage your active OAuth connections:

• See which AI clients are connected and when they last authenticated
• View the organization and API key linked to each authorization
• Revoke individual authorizations (this soft-deletes the OAuth tokens and cleans up auto-created API keys)
• Revoke all authorizations for a specific client

Using with Cursor

Add the following to your project's .cursor/mcp.json file:

{
  "mcpServers": {
    "ocore": {
      "type": "sse",
      "url": "https://your-ocore-domain.com/api/mcp/sse",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Cursor will discover the MCP server and make the tools available in chat and the agent panel.

Device Flow for CLI Tools

If you are using a CLI tool or working in an environment without browser redirects (SSH sessions, containers), the device authorization flow lets you authenticate:

Device codes expire after 15 minutes. If the code expires before you approve, the CLI tool will need to request a new one.

MCP Invite Links

An administrator can share an MCP invite link that lets you connect to their organization without going through the full OAuth consent flow. When you receive an invite link:

If you are not already a member of the organization, oCore automatically adds you as a Viewer. The invite's permissions cannot exceed the admin's own permissions -- scope escalation is prevented.

Using with Other MCP Clients

oCore supports two MCP transports:

• SSE (Server-Sent Events) at /api/mcp/sse -- for browser-based and long-lived connections
• Streamable HTTP at /api/mcp/stream -- for stateful HTTP-based clients

Any MCP-compatible client can connect by pointing to one of these endpoints. Clients that support OAuth will discover the authorization server automatically. For clients without OAuth support, include a valid API key in the Authorization: Bearer header.

Available Tools

oCore exposes 101 tools across 14 categories. Each instance-scoped tool is prefixed with the instance slug (e.g., myinstance_search_read). Platform tools use the ocore_ prefix.

Tool Categories Overview

Common Parameters

Most tools accept these optional parameters:

ORM Operations

Core CRUD operations on Odoo models. Category: orm.

Search and Aggregation

Advanced search tools for complex queries. Category: search.

Batch Operations

Bulk operations on multiple records. Category: orm (uses ORM permission category). Max batch size: 500.

Schema and Metadata

Inspect Odoo model definitions and instance configuration. Category: metadata.

SQL Queries

Direct PostgreSQL access. Category: sql.

Shell and Code Execution

Execute Python code in the Odoo environment. Category: shell. All shell tools require mcp_write_enabled.

File Operations

Read and modify files in Odoo addon directories. All paths are relative to the instance's custom addons root and sandboxed to prevent directory traversal. Category: files.

Module Management

Install, upgrade, and inspect Odoo modules. Category: modules. Install/upgrade/uninstall operations enforce a minimum 90-second timeout.

User and System Administration

Manage Odoo users, system parameters, cron jobs, and server operations. Category: system.

Database Backup and Restore

Create, list, and restore database backups. Category: system.

Knowledge and Context

Persistent knowledge storage and reusable filters for AI sessions. Category: context.

Notes

Saved Filters

Bookmarks and Context

Analytics and Monitoring

PostHog-powered analytics for Odoo instances. Category: monitoring. Requires PostHog to be configured. All tools accept a period parameter (1d, 7d, 14d, 30d, 90d).

CSV Import and Export

Bulk data import/export via CSV. Category: orm (uses ORM permission category).

Translations

Read and update Odoo translations. Handles both Odoo 17 (ir.translation model) and Odoo 18+ (field translation API) automatically. Category: metadata.

Attachments

Manage Odoo file attachments (ir.attachment). Category: attachments. Max file size: 10 MB.

Reports

Generate Odoo QWeb reports. Category: reports.

Platform Tools

These tools are not instance-scoped and use the ocore_ prefix instead of an instance slug. Category: platform.

Knowledge Layer

The Knowledge Layer is a persistent storage system that lets AI assistants accumulate and reuse knowledge about your Odoo instances across sessions. It consists of three data types -- notes, saved filters, and bookmarks -- all scoped to your organization and optionally to specific instances.

Notes

Notes store human or AI-authored knowledge about your Odoo environment. Each note is attached to a specific target:

Notes properties:

• Title -- Up to 200 characters
• Body -- Up to 2,000 characters of content
• Tags -- Optional array of tags for filtering (e.g., ["summary", "workflow"])
• Shared -- Notes are shared across all API keys in the organization
• Limit -- Up to 100 notes per scope to prevent unbounded growth
• Soft delete -- Deleted notes are soft-deleted and excluded from queries

Summary Notes

Notes tagged with "summary" have special significance. The set_model_summary and set_instance_summary tools upsert a single summary note per target, making it easy to maintain one authoritative description. Summary notes are used by auto-context (see below) to inject knowledge into tool descriptions at session start.

Saved Filters

Saved filters store reusable Odoo domain searches that can be executed by name:

Saved filters let an AI assistant quickly recall complex queries without re-specifying the domain each time. Use list_filters to see available filters (sorted by most-used first) and run_filter to execute one.

Bookmarks

Bookmarks save references to important MCP tool calls for future reference:

Bookmarks store an inline snapshot of the tool call so they remain useful even if audit log entries are later purged. If no audit_log_id is provided when bookmarking, the system bookmarks the most recent call in the current session.

Auto-Context

When an API key has mcp_auto_context enabled, oCore automatically injects Knowledge Layer data into tool descriptions at session start. This gives the AI assistant immediate context without requiring an explicit get_context call.

At session registration time, oCore runs a parallel query (with a 5-second deadline) for each instance:

1. Instance summary -- Loads the note tagged "summary" with target_type=instance
2. Model summaries -- Loads up to 20 notes tagged "summary" with target_type=model, showing the model name and a 150-character excerpt
3. Saved filter count -- Counts available saved filters and mentions them if any exist

The results are prepended to each instance's tool descriptions as an [Auto-context] prefix. For example:

[Auto-context] Instance context: EU production instance with custom VAT workflow.
Model summaries: sale.order: Custom approval fields x_approved_by, x_delivery_notes;
account.move: Modified to support split VAT for EU cross-border. 3 saved filters
available -- call get_context for details.

Loading Full Context

The get_context tool loads the complete Knowledge Layer for an instance in a single call:

• Instance summary note
• All model summary notes
• All notes (non-summary, up to limit)
• All saved filters with name, model, and description
• Recent bookmarks (up to 50)

This is useful at the beginning of a session when auto-context is not enabled, or when the assistant needs the full detail beyond what auto-context provides.

Security

oCore's MCP server enforces multiple layers of security on every tool call:

Authentication

Every MCP session requires a valid API key. Keys are periodically revalidated against the database (every 30 seconds) to detect revocation, expiration, or user deactivation mid-session.

Instance Scoping

API keys can be scoped to specific instances. A key scoped to prod-v17 will only see tools for that instance -- no other instances are visible or callable.

RBAC Categories

API keys can be restricted to specific tool categories (e.g., orm, sql, metadata). If a key only has orm and metadata permissions, shell and SQL tools are blocked. An empty permission list grants full access.

Read-Only Mode

Keys can be marked as read-only, which blocks all write and destructive operations while still allowing search, read, and metadata inspection tools.

Production Guard

Each instance has a mcp_write_enabled flag. When disabled (the default for production instances), all write operations are blocked regardless of the API key's permissions. This prevents accidental data modification in production.

Destructive Operation Confirmation

High-risk tools require a confirm: true parameter. Without it, the tool returns a warning message describing what would happen instead of executing. The following tools are marked destructive:

• unlink, batch_delete -- record deletion
• execute_sql_script -- multi-statement SQL
• file_delete -- file deletion
• uninstall_module -- module removal
• clear_system_cache -- cache clearing
• restore_database -- database restore
• delete_note, delete_filter, delete_bookmark -- knowledge deletion

IP Allowlist

API keys can include an IP allowlist. Connections from IPs not on the list are rejected.

Kill Switch

Organization administrators can disable MCP access entirely via the organization settings toggle. This immediately blocks all MCP tool calls for every key in the organization.

Rate Limiting

Per-key rate limiting prevents abuse:

Tool Allow/Deny Lists

API keys support per-tool filtering with allow or deny lists, giving fine-grained control over which specific tools a key can invoke.

Model Allowlist

API keys can restrict which Odoo models are accessible. When a model allowlist is set, list_models only returns models in the allowlist, and ORM operations on other models are rejected.

Input Validation

All tool inputs are validated before execution:

• Model names, field names, and method names are checked against a strict identifier pattern ([a-zA-Z_][a-zA-Z0-9_.]*).
• SQL queries are stripped of comments and strings, then scanned for DDL, dangerous functions, and blocked statements.
• File paths are sandboxed to the instance's addon directory with traversal prevention.
• User IDs 1-3 (admin, public, __system__) cannot be modified by user management tools.

Audit Logging

Every MCP tool call is recorded in a dedicated mcp_audit_log table with:

• Tool name and category
• Input parameters (sensitive values like passwords are automatically redacted)
• Result summary (truncated to 500 characters)
• Whether the call succeeded or errored
• Latency in milliseconds
• Session ID, API key ID, user ID, and IP address

High-level session events (session started, session ended) are also logged to the main audit log.

Prompt Templates

oCore includes built-in MCP prompt templates that AI assistants can use for guided analysis:

Example Usage Patterns

Exploring an instance

1. ocore_list_instances          -- discover available instances
2. myinstance_get_instance_info  -- get version, environment, status
3. myinstance_server_info        -- Odoo server details
4. myinstance_list_models search="sale"  -- find sale-related models
5. myinstance_get_field_metadata model="sale.order"  -- understand the schema

Searching and reading data

1. myinstance_search_read model="res.partner" domain=[["is_company","=",true]] fields=["name","email"] limit=10
2. myinstance_aggregation model="sale.order" fields=["amount_total:sum"] groupby=["state"] format="table"
3. myinstance_count model="sale.order" domain=[["state","=","sale"]]
4. myinstance_fuzzy_search model="res.partner" query="Acme Corp" min_score=0.6

Modifying data safely

1. myinstance_create model="res.partner" values={"name":"New Partner","email":"new@example.com"}
2. myinstance_write model="res.partner" ids=[42] values={"phone":"+1234567890"}
3. myinstance_unlink model="res.partner" ids=[99] confirm=true

Working with modules

1. myinstance_list_modules state="installed"
2. myinstance_module_dependencies addon="sale"
3. myinstance_check_uninstall_deps module="sale_stock"
4. myinstance_install_module module="sale_management"

Debugging with SQL and logs

1. myinstance_execute_sql query="SELECT id, name FROM res_partner WHERE active = false LIMIT 10"
2. myinstance_odoo_logs lines=200 filter="ERROR"
3. myinstance_execute_sql query="SELECT state, count(*) FROM sale_order GROUP BY state"

Using knowledge context

1. myinstance_get_context           -- load all saved knowledge at session start
2. myinstance_set_model_summary model="sale.order" summary="Main sales model. Custom fields: x_approved_by, x_delivery_notes."
3. myinstance_save_filter name="large_orders" model="sale.order" domain=[["amount_total",">",10000]] fields=["name","partner_id","amount_total"]
4. myinstance_run_filter name="large_orders"

Troubleshooting

Tools not appearing in the AI assistant

• Verify the API key is valid and not expired or revoked
• Check that the organization has MCP enabled (kill switch is off)
• Confirm at least one instance is in running status
• Check your AI client's MCP configuration for syntax errors

Tool calls returning "unauthorized"

• The API key may have been revoked or expired since the session started
• The owning user account may have been deactivated
• The organization may have toggled MCP off via the kill switch

Tool calls returning "permission denied"

• The API key's MCP permissions do not include the tool's category
• Check the key's category list and add the required category (e.g., sql, shell)
• Keys with no explicit permissions have full access to all categories

Write operations blocked

• The instance has mcp_write_enabled set to false (production guard)
• The API key is in read-only mode
• For destructive operations, include confirm: true in the tool arguments

Rate limit exceeded

• Reduce the frequency of tool calls
• Contact your administrator to adjust rate limits if the default is too low for your use case

Shell/SQL tools timing out

• Increase the timeout_seconds parameter (max 120 seconds)
• For module operations, the minimum timeout is automatically raised to 90 seconds
• For report generation, the minimum timeout is automatically raised to 60 seconds
• Long-running SQL queries have a statement_timeout set automatically