MCP tool reference

The complete set of tools the built-in MCP server exposes to a connected AI agent. There are 19 tools in four groups: data (read and write records), schema (discover models and your access), live capability (what this workspace runs right now), and website (edit the site copy-on-write). Every tool runs as the connected user and is bounded by that user's permissions. For how to connect an agent and the guardrails that sit on top of these tools, see AI agents & MCP.

The 19 tools

Data tools

Run as the connected user, bounded by that user's roles and record rules.

Tool	Required args	What it does
search	model	Search and read fields (search_read) on a model. Binary fields are omitted unless you name them; at most 500 rows.
get	model, ids	Read specific records by id.
count	model	Count records matching a domain.
find	model, name	Fuzzy name search (name_search); resolves a label to record ids.
create	model, values	Create a record and return its id. Security-critical models and fields are blocked.
update	model, ids, values	Write field values onto existing records. More than 100 records needs confirm:true.
delete	model, ids	Delete records (irreversible). Needs confirm:true; returns a preview otherwise.
call	model, method	Call a public model method (e.g. action_confirm, message_post). Non-read methods need confirm:true.

Schema tools

Read the model layer. Schema is read with elevated rights; your data operations stay bounded by your role.

Tool	Required args	What it does
list_models	—	List installed models, optionally filtered, to discover what this workspace has.
describe_model	model	Describe a model's fields and your access to it (read / create / write / unlink).

Live-capability tools

Report this workspace's actual current state, so no stale document can misstate what is installed.

Tool	Required args	What it does
platform_info	—	Version, base URL, installed apps, the MCP server version and tool list, and your admin status. Call this first.
list_installed_modules	—	Installed modules (name, description, version); apps_only:true for applications only.
whats_new	—	Recently installed or updated modules, ordered by last change.

Website tools

Run as the connected user and need website-designer rights. Edits are copy-on-write.

Tool	Required args	What it does
website_pages	—	List the site's pages (url, view, published/indexed, in-menu). Start here.
website_new_page	name	Create a page from a template (copy-on-write). Returns its url and ids.
website_edit_page	arch	Rewrite a page's full QWeb arch, copy-on-write into a site-specific view. Read the arch first.
website_publish	—	Publish or unpublish a page, and optionally toggle sitemap indexing.
website_menu	—	List nav menu items, or add one (name + url).
website_redirect	url_from, url_to	Create a 301/302 redirect.

How results come back

Every successful call is wrapped MCP-style: {"content": [{"type": "text", "text": <json>}], "structuredContent": <json>, "isError": false}. The shapes below describe the structuredContent. Each result also carries a _count key. A permission or validation failure comes back as a clean tool error (isError: true, "Error: <message>"); any other failure is logged server-side and surfaced only as an opaque reference, so internals never leak.

Parameters and return shapes

search

Search and read fields on a model, bounded by your permissions. Binary fields are omitted unless you name them; at most 500 rows.

• Parameters: model* (string, e.g. crm.lead), domain (array of triples), fields (array of strings), limit (integer, default 50, capped at 500), offset (integer), order (string).
• Returns: {"records": [{...}], "_count": n}. Secret-named fields come back as "***".

get

Read specific records by id.

• Parameters: model* (string), ids* (array of integers), fields (array of strings).
• Returns: {"records": [{...}], "_count": n}. Ids are clamped to 500; secret-named fields are masked.

count

Count records matching a domain.

• Parameters: model* (string), domain (array of triples).
• Returns: {"count": n, "_count": n}.

find

Fuzzy name search (name_search); resolve a label to record ids.

• Parameters: model* (string), name* (string), limit (integer, default 20).
• Returns: {"results": [{"id": i, "name": s}], "_count": n}.

create

Create a record. Security-critical models and fields are blocked.

• Parameters: model* (string), values* (object).
• Returns: {"created_id": id, "display_name": s, "_count": 1}.

update

Write field values onto existing records. Security-critical models and fields are blocked.

• Parameters: model* (string), ids* (array of integers), values* (object), confirm (boolean, default false).
• Returns: {"updated_ids": [...], "_count": n}. More than 100 ids without confirm:true returns {"confirm_required": true, "message": ..., "_count": 0} and writes nothing.

delete

Delete records. Irreversible.

• Parameters: model* (string), ids* (array of integers), confirm (boolean, default false).
• Returns: with confirm:true, {"deleted_ids": [...], "_count": n}. Without it, a preview: {"confirm_required": true, "would_delete": [{"id", "name"}], "_count": 0} — nothing is deleted.

call

Call a public model method (e.g. action_confirm, message_post). The mutating verbs (write / create / unlink) are blocked here; use their own tools. Calls route through the platform's public-method gate, so private methods are refused.

• Parameters: model* (string), method* (string), ids (array of integers), args (array), kwargs (object), confirm (boolean, default false).
• Returns: {"result": ..., "_count": n}. A recordset result is coerced to {"model": name, "ids": [...]}. A non-read method without confirm:true returns {"confirm_required": true, ...}.

list_models

List installed models, optionally filtered.

• Parameters: filter (string), limit (integer, default 500).
• Returns: {"models": [{"model", "name"}], "_count": n}. Non-transient models only.

describe_model

Describe a model's fields and your access to it.

• Parameters: model* (string).
• Returns: {"model", "your_access": {"read", "create", "write", "unlink"} (booleans, your real access), "fields": [{name, string, type, required, readonly, relation, selection, help}], "_count": n}.

platform_info

This workspace's live state. Call it first to orient.

• Parameters: none.
• Returns: {"tenant_db", "base_url", "odoo_version", "mcp_server": {name, version, tools, tool_count}, "installed_module_count", "applications": [...], "your_user": {login, is_admin}, "_count": n}.

list_installed_modules

The modules this workspace actually runs.

• Parameters: filter (string), apps_only (boolean).
• Returns: {"modules": [{name, shortdesc, installed_version, application}], "_count": n}.

whats_new

Recently installed or updated modules, ordered by last change.

• Parameters: limit (integer, default 20).
• Returns: {"recently_changed_modules": [{...}], "note", "_count": n}.

website_pages

List the site's pages. Start here for any website work.

• Parameters: website_id (integer).
• Returns: {"website": {id, name, domain}, "pages": [{id, url, name, view_id, published, indexed, in_menu, website_specific}], "_count": n}.

website_new_page

Create a page from a template, copy-on-write.

• Parameters: name* (string), template (string, default website.default_page), add_menu (boolean, default true), published (boolean, default false), website_id (integer).
• Returns: {"created": {...}, "_count": 1}.

website_edit_page

Rewrite a page's full QWeb arch, copy-on-write into a site-specific view, so upgrades never overwrite it. Read the current arch first.

• Parameters: arch* (string, the complete QWeb template), url (string) or page_id (integer), website_id (integer).
• Returns: {"page_id", "url", "view_id", "website_specific", "_count": 1}.

website_publish

Publish or unpublish a page, and optionally toggle sitemap indexing.

• Parameters: url (string) or page_id (integer), published (boolean, default true), indexed (boolean), website_id (integer).
• Returns: {"page_id", "url", "published", "indexed", "_count": 1}.

website_menu

List nav menu items, or add one.

• Parameters: list (boolean) to list; or name (string) + url (string) to add, with parent_id (integer), sequence (integer), new_window (boolean), website_id (integer).
• Returns: listing, {"menus": [{...}], "_count": n}; adding, {"menu_id", "name", "url", "_count": 1}.

website_redirect

Create a 301 or 302 redirect.

• Parameters: url_from* (string), url_to* (string), redirect_type (string, default 301), name (string), website_id (integer).
• Returns: {"rewrite_id", "url_from", "url_to", "type", "_count": 1}.

Related

• AI agents & MCP — connect an agent, and the guardrails on these tools.
• Integration & agent users — the account a key should belong to.
• External API — the same operations over the JSON API.