Keys and scopes
A key is what an outside AI program shows to reach your database. A key belongs to one Odoo user. It can only be narrower than that user, never wider.
Who this is for: administrators and users who create keys.
You need: Edition: Business (module minddesk_mcp). See Editions.
Create a key
Open Configuration ▸ MCP ▸ Keys and press New.
- Give the key a name that says what it is for.
- Set the owner. A MitDesk user can create and manage only their own keys. An administrator can manage all keys.
- Choose what it may reach (see below).
- Press Generate & Connect. A dialog shows the token, the address and the settings for Claude Desktop, Claude Code and Cursor.
What you should see: after step 4, a dialog with the token, the address and the settings.
The token is shown only once. MitDesk stores a SHA-256 hash and the first eight characters (the prefix), nothing else. If you close the dialog without copying the token, you cannot see it again. Create a new token instead. A revoked key cannot create a token.
Set an Expires at date if the key is only for a limited time. After that date the key stops working.
Narrower than the owner
The owner's own Odoo rights are always the upper limit. A key can only reduce them.
Models. Leave Every model the owner may read on, and the key reaches all of them. Turn it off and pick the models from a list. A key with no models picked reaches nothing.
Record boundaries. A boundary is a filter for one model. MitDesk adds it to every call and checks it again each time. A date range means what it means today. If a program asks for a record outside the boundary, MitDesk refuses clearly. It does not just return a shorter list. A model with a boundary cannot create new records, because a new record cannot be tested against the filter. A path that goes through a bounded model is also refused.
What this key may do. The boxes are Read, Update, Create and Delete. A new key can only read.
Tools. You can choose tools to expose and tools to withhold from a list, or with patterns (for example analytics_*). A pattern may use *, ? and [...]. Withheld tools win. The tool health_check is always available. Two administrator-only buttons, See the tools this key exposes and See the prompts, ask the server what a program with this key would really see.
Fields. The Field / PII Blocklist lists fields that a program can never use. The default is iban,password,password_crypt,api_key,secret,token. Some fields, such as acc_number, are blocked in addition. A blocked field cannot be read, filtered, grouped or summed. A file's content is blocked under all its names (datas, raw, db_datas, index_content). If you need an exception, write the exact model.field in Explicit Field Exceptions. Wildcards are not allowed. Only an administrator can approve an exception.
Companies and addresses. Allowed Companies must belong to the owner. If you leave it empty, the key uses only its home Company. A program cannot change the company by itself. Allowed source addresses is a list of IP addresses or ranges. Empty means any address.
Outbound confirmation. This decides how calls to remote MCP servers are confirmed: Stateful, single-use, or Stateless HMAC, 15-minute replay window. Local and financial operations are always stateful and single-use.
Rate limits
You set three limits. For each of them, 0 means no limit.
- Rate limit: requests each minute.
- Rate limit per second: a separate cap for short bursts.
- Daily call limit: authenticated requests in one day (UTC).
The counters are kept in the database on the key itself. The limit is therefore the same however many Odoo workers you run. A program that is slowed down is told how long to wait. Throttles and exceeded limits go to the audit log.
The tab Activity shows the use of the key: calls today, last used, last IP address and total calls.
Confirm before a change
A call that changes data and has no confirmation does not run. The server sends back a preview and a confirmToken. The token is valid for ten minutes, works once, and fits only this key, this tool and these arguments.
A confirmation only says that the program meant this call. It is not an approval. The call can still wait for a person. See Connecting an external AI.
A program can also add dry_run: true to a changing call. It then gets a list of the changes and nothing is done. A dry run cannot use a confirmation token.
Rotate, revoke and switch off
- Rotate key makes a new key with the same owner, scope, limits and boundaries. Before you rotate, set Rotation grace minutes on the Advanced tab (administrators only). The old key works for that time. With 0 it stops at once. Change the token in every program, check that the new key shows Last used at, then revoke the old key.
- Revoke switches off one key at once. Use it for a lost token or for strange activity.
- Deactivate the Odoo user. Every key of that user stops working.
- Switch off MCP. Set the system parameter
minddesk.mcp_enabledtoFalse.
Scope suggestions
When a program is refused because a model or field is outside the key, MitDesk counts the refusal. On the key form, an administrator can open Scope Suggestions. The list shows the most refused targets first. For each target, the administrator chooses:
- Add to scope: adds only the exact model, or only the exact field exception. It never changes the operations or the application scope.
- Confirm deny: keeps the target blocked and hides repeated reports.
Refusals caused by a record boundary are never suggested, because there the boundary worked as planned.
Business vocabulary
In Configuration ▸ MCP ▸ Business vocabulary an administrator maps the words Customer, Order, Invoice and Asset to a model, for each company. If there is no entry, MitDesk uses res.partner, sale.order, account.move and account.asset when they are installed. A program can then ask for business:customer. The word only names a model. All the rules above still apply, and the word is refused in changing tools.
See also Connecting an external AI and Document intelligence.
If it does not work
If a program is refused, check the key's scope and its Expires at date. See also Troubleshooting.