Skip to main content
Odoo 20 MCP Server: Connect Claude Code, Codex & External AI Agents
8 min read
Odoo

Odoo 20 MCP Server: Connect Claude Code, Codex & External AI Agents

Learn how the Odoo 20 MCP server connects external AI clients using API-key authentication, exposed tools, read-only controls and Odoo permissions.

Odoo 20 includes an MCP server that allows compatible external AI clients to interact with an Odoo database through controlled tools.

Current official Odoo documentation includes setup examples for clients including Claude Code and Codex. Authentication uses an Odoo API key, and the MCP endpoint follows the database URL with /mcp.

The important architectural point is that MCP is not a generic “AI gets database access” switch.

The client can use only the capabilities Odoo exposes, under the permissions of the authenticated Odoo user.

What MCP is

Model Context Protocol is a standard for exposing tools/context to compatible AI clients.

For Odoo, the simplified flow is:

text
AI client
   ↓ MCP
Odoo /mcp
   ↓
Exposed tools / server actions
   ↓
Odoo models and business logic

This makes Odoo a tool provider for an external AI environment.

Authentication

Odoo documents API-key authentication for MCP.

Treat the API key like a password:

  • never commit it to Git;
  • do not paste it into screenshots;
  • use environment/secret management;
  • rotate it when exposure is suspected;
  • use a dedicated least-privilege Odoo user when appropriate.

The authenticated user’s permissions are part of the security model.

Connecting Claude Code

Odoo’s current MCP documentation includes a Claude Code configuration example.

Use the exact current command/configuration from the official documentation rather than copying an old blog post, because client syntax can change.

Conceptually, you configure:

  • the Odoo MCP endpoint;
  • the Odoo API key;
  • the compatible MCP client.

Then test a harmless read-only request first.

Connecting Codex

Odoo’s current documentation also includes Codex configuration.

Again, prefer the official current client syntax.

Start with a read-oriented workflow such as discovering permitted models/fields or searching test records before exposing business-changing tools.

Default tools and custom tools

Odoo exposes a limited default tool set.

Additional server actions can be made available by enabling Available in MCP.

That is a powerful control point.

Instead of giving an external agent a generic “write anything” operation, expose purpose-built tools such as:

  • search approved records;
  • create a follow-up activity;
  • prepare a draft note;
  • return a controlled report;
  • trigger a validated workflow.

Readonly Tool

Odoo documents a Readonly Tool designation for tools that do not write or modify records.

Use it accurately.

A tool marked read-only should not create hidden side effects.

Read-only tools are a good place to start because they reduce the blast radius while you evaluate agent behavior.

Design tools around business operations

Bad tool:

arbitrary_model_write(model, ids, values)

Better tool:

schedule_sales_followup(opportunity_id, due_date, note)

The second operation has a business meaning that can be validated.

Inside the tool, enforce:

  • allowed model;
  • allowed fields;
  • required state;
  • user permissions;
  • company context;
  • validation;
  • audit trail.

The AI chooses a permitted action. The tool remains responsible for correctness.

MCP vs JSON-2

Use MCP when an AI client needs to interpret a task and choose approved tools.

Use JSON-2 when another application needs deterministic API calls.

Example MCP:

“Find neglected high-value opportunities and prepare follow-up actions.”

Example JSON-2:

“Create an Odoo order from this validated eCommerce payload.”

Do not replace reliable deterministic integration code with an LLM just because MCP exists.

Security checklist

Before exposing MCP:

  • create a dedicated test database;
  • use least-privilege users;
  • start read-only;
  • inventory every exposed tool;
  • review tool implementation;
  • validate company/access rules;
  • protect API keys;
  • avoid broad generic write tools;
  • test unauthorized requests;
  • test ambiguous prompts;
  • require human approval for high-impact operations;
  • monitor/audit important actions.

A safe proof of concept

  1. Create a non-production Odoo 20 database.
  2. Create a limited test user.
  3. Generate an API key.
  4. Configure the supported AI client using the current official syntax.
  5. Connect to /mcp.
  6. Test model/field discovery.
  7. Test a search.
  8. Add one purpose-built read-only tool.
  9. Evaluate expected and adversarial prompts.
  10. Only then consider a constrained write tool.

Common mistakes

  • Using an administrator API key for convenience.
  • Exposing generic write operations.
  • Assuming MCP bypasses normal access-control design.
  • Putting business validation only in the prompt.
  • Giving the agent too many tools at once.
  • Treating “Readonly Tool” as a label rather than a behavioral promise.
  • Using MCP for deterministic integrations that should remain normal API calls.

Exact Odoo 20 MCP setup

Odoo's current documentation makes the setup concrete.

Create an MCP-scoped API key

From My Preferences → Security, create an API key and select the MCP scope. Odoo also lets you set an expiration period. The key is displayed only once, so store it securely.

MCP endpoint

Use the database URL plus /mcp:

text
https://your-database.example.com/mcp

Claude Code

Odoo currently documents this pattern:

bash
claude mcp add --transport stdio <server_name> -- \
  npx -y mcp-remote <database_url>/mcp \
  --header "Authorization: Bearer <API_KEY>"

Check the connection with:

bash
claude mcp list

Codex

Current Odoo documentation provides:

bash
codex mcp add <server_name> -- \
  npx -y mcp-remote <database_url>/mcp \
  --header "Authorization: Bearer <API_KEY>"

Start Codex and use /mcp to inspect the server. Verify client syntax against current docs before production because client CLIs can evolve.

Default MCP tools in Odoo 20

Current documentation lists these default exposed tools:

  • AI Tool: Get Fields
  • AI Tool: Get Models
  • AI Tool: MCP Retrieve initial context
  • AI Tool: Search
  • AI Tool: Read group

Other server actions remain hidden until Available in MCP is enabled.

What Readonly Tool really means

Odoo says Readonly Tool does not hide the tool. It advises the client that the tool does not write/modify existing data and may be automatically invoked without user approval.

Only mark a tool read-only when its implementation truly has no write side effects.

MCP troubleshooting

Client cannot connect

Check /mcp, MCP-scoped key, expiration, database reachability, and Node.js/npx requirements for the documented remote-client setup.

Tool does not appear

Check Available in MCP, reconnect/refresh the client's cached tool list, and verify the relevant app/tool is installed.

Access error

The API key authenticates an Odoo user identity and permissions. Review ACLs, record rules and company context.

Wrong tool is chosen

Make tool names/descriptions distinct and scopes narrow. Similar broad tools make selection harder.

MCP security model

Threat-model prompt injection, excessive user permissions, secret exposure, irreversible actions and generic write tools.

For high-impact operations, prefer: AI proposes → validated tool checks → human approves where appropriate → Odoo executes.

MCP tool design example

Suppose sales management wants an external AI client to help with neglected opportunities.

Avoid exposing a generic write tool.

Instead define a controlled operation conceptually like:

text
schedule_followup(
    opportunity_id,
    due_date,
    note
)

The Odoo-side implementation should verify:

  • the opportunity exists;
  • the authenticated user may access it;
  • the company context is valid;
  • the due date is allowed;
  • the note meets expected constraints;
  • the operation creates only the intended activity.

The model can decide when the tool is appropriate. Odoo code decides whether the requested operation is valid.

Threat-model the MCP connection

Consider:

Prompt injection

Untrusted text in a record/document may attempt to manipulate the agent. Tools should remain constrained even if the model receives malicious instructions.

Excessive permissions

A powerful Odoo user turns every exposed tool into a higher-impact capability.

Tool confusion

Similar tools can cause the model to choose the wrong operation. Keep names/descriptions distinct and scopes narrow.

Secret exposure

API keys should never be included in prompts, screenshots, repositories or client logs.

Irreversible actions

Deletion, posting, payment, access changes and other high-impact operations deserve stronger controls or human approval.

Production rollout checklist

  • Non-production database tested.
  • Dedicated least-privilege user considered.
  • API key stored securely.
  • Every exposed tool inventoried.
  • Read-only behavior verified.
  • Write tools have deterministic validation.
  • Company/access rules tested.
  • Prompt-injection scenarios tested.
  • High-impact actions require appropriate approval.
  • Audit/monitoring plan defined.
  • Key rotation/revocation procedure documented.

MCP makes the interface convenient. It does not remove normal application-security responsibilities.

FAQ

Does Odoo 20 have an MCP server?

Yes. Odoo 20 documentation describes an MCP server available through the database /mcp endpoint.

Can Claude Code connect to Odoo 20?

Current Odoo MCP documentation includes Claude Code setup instructions.

Can Codex connect to Odoo 20?

Current Odoo MCP documentation includes Codex configuration instructions.

Does MCP give AI full access to Odoo?

Not inherently. Access depends on the authenticated Odoo user and exposed tools/server actions. Design both conservatively.

Is MCP a replacement for the Odoo API?

No. MCP is well suited to AI-tool interaction. JSON-2/custom APIs remain appropriate for deterministic application integrations.

Final takeaway

The Odoo 20 MCP server is valuable because it gives external AI systems a controlled interface to ERP capabilities.

Its safest use is not “let the AI access everything.”

It is:

authenticate narrowly, expose intentionally, validate deterministically, and expand capability only after testing.

Planning an Odoo 20 project? Octivex Tech helps businesses with Odoo upgrades, custom module migration, integrations and AI-enabled workflows. Explore our Odoo services or contact our engineering team to discuss your environment.

Related reading

Odoo field notes on the same subject.

Back to all posts