> ## Documentation Index > Fetch the complete documentation index at: https://docs.codecobra.ai/llms.txt > Use this file to discover all available pages before exploring further. # Connect an Odoo environment > Step-by-step guide to giving CodeCobra access to a real Odoo instance over MCP. CodeCobra's agent can talk to your real Odoo databases through the MCP (Model Context Protocol) bridge. Adding an environment lets the agent **read records, run searches, and — if you opt in — write changes** in your live Odoo instance instead of only the disposable onboard pod. This guide walks you through every step. No prior MCP knowledge needed. You can add an Odoo environment in two places: * **During project creation**, in the *Odoo* step of the setup wizard. * **Anytime later**, in **Project → Settings → Odoo Environments**. Both flows use the same form and validation. The wizard is identical to the settings page — pick whichever is easier. ## Before you start You'll need three things: 1. **The base URL of your Odoo instance** — the same address you'd type into a browser, e.g. `https://acme.odoo.com` or `https://erp.example.com`. 2. **An Odoo user** that the agent will log in as. We strongly recommend creating a dedicated user instead of reusing your admin account — see [Create a dedicated user](#create-a-dedicated-odoo-user) below. 3. **An API key** for that user (or, on legacy Odoo, the user's password). CodeCobra encrypts your API key at rest, but the agent can only do what the linked Odoo user is allowed to do. **Tier (Read / Write / Delete) controls *what kinds* of actions the agent can attempt — it does not restrict *which* records the agent can see.** Scoping by record / model / module is configured on the Odoo side via groups and record rules. ## Create a dedicated Odoo user Skip this if you already have a user you want the agent to act as. In your Odoo instance, go to **Settings → Users & Companies → Users** and click **New**. * **Name**: `CodeCobra Agent` (or whatever you want to see in audit logs) * **Email / login**: a unique address, e.g. `codecobra@yourcompany.com` * **User type**: *Internal User* Under the **Access Rights** tab, give the user only the modules and record-rule groups the agent should be able to touch. If you only want read access, do not grant any *manager* roles. For a first try, copy the access rights from a normal employee account — that's usually enough for the agent to explore data without being able to break anything sensitive. Click **Save**. You'll come back to this user in a moment to create the API key. ## Generate an API key Odoo 14+ supports per-user API keys, which are safer than passwords. Click the user's avatar in the top-right corner of Odoo (while logged in *as that user*) and choose **My Profile** (or **Preferences**). Find the **Account Security** tab. You'll see a section labelled **Developer API Keys**. Click **New API Key**. Give it a name like `CodeCobra` and a sensible expiration (e.g. 1 year). Odoo will ask you to re-enter the password to confirm. Copy the generated key immediately. You won't be able to view it again — if you lose it, you'll have to delete the key and create a new one. Paste it into a temporary note; you'll need it in the next section. If you're on a **very old Odoo (≤13)** that doesn't have API keys, you can use the user's password instead. Pick **Password (legacy)** as the *Auth method* in the form below. We strongly recommend upgrading or using a dedicated low-privilege user. ## Find the database name Most users only have one database, in which case CodeCobra will detect it automatically. Some self-hosted setups host multiple databases on a single Odoo instance — here's how to be sure: * **Odoo Online (`*.odoo.com`)**: the database name is the subdomain. `acme.odoo.com` → `acme`. * **Self-hosted**: open `/web/database/manager` on your Odoo instance (e.g. `https://erp.example.com/web/database/manager`). Each row is a database; the column on the left is the name. * **Already logged in?** In Odoo, open **Settings → Technical → Database Structure → Database** (or look at the Sentry / Grafana setup your team uses). If the database picker in the form below shows a warning that the server won't list databases, your Odoo admin has set `list_db = False` in `odoo.conf` (a common production setting). It's not a bug — type the name in by hand. ## Add the environment in CodeCobra * **From the project setup wizard**: on the *Odoo* step, click **Add Odoo environment**. * **From an existing project**: open **Settings → Odoo Environments**, then click **Add Odoo environment**. * **Name** — a label you'll see in the chat composer. Use names like `Production`, `Staging`, `Demo` so it's obvious what you're pointing the agent at. * **Tier** — see [Access tiers](#access-tiers) below. Default to **Read** if you're not sure. * **Base URL** — paste the URL exactly as you'd open it in a browser. CodeCobra will auto-add `https://` if you forget the scheme. A green checkmark next to the field confirms the URL responds to Odoo's XML-RPC endpoint. * **Database** — pick from the dropdown. If only one database exists on the server, it's selected automatically. * **Login** — the email / login of the Odoo user you created above. * **Auth method** — leave as **API key** unless you're on Odoo ≤13. * **API key** — paste the key you copied in the previous section. Click **Test connection** before saving. CodeCobra will: 1. Reach the `/xmlrpc/2/common` endpoint. 2. Authenticate with your login + key against the chosen database. 3. Return the Odoo version it found. If something fails, the form tells you exactly what — `unreachable`, `auth_failed`, etc. — see [Troubleshooting](#troubleshooting). Click **Add environment**. The credential is encrypted with the project's Fernet key and stored in the database. The plaintext key never leaves your browser after this point. ## Access tiers Each environment has a **tier** that decides which MCP tools the agent can call against it. | Tier | What the agent can do | When to use it | | ------ | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | Read | Searches, record reads, counts, grouped totals, schema inspection, reports — **read-only** | Production. Default when in doubt. | | Write | Everything in Read **plus** creating records, updating fields, and triggering business actions — **never delete** | Staging, or a production env where the agent should be able to update records with your approval. | | Delete | Everything in Write **plus** permanently deleting records | Disposable sandbox / dev databases you can roll back. | Write and Delete let the agent change real records. As an extra guard, every change to one of your environments also requires an explicit **in-chat approval** from you before it runs — the agent describes exactly what it's about to change and asks first, once per conversation turn. Restrictions inside Odoo (record rules, user groups) still apply — the tier only widens the *kinds* of operations the agent will attempt. ## Use an environment in a chat Once an environment is saved, every chat in that project can point the agent at it: 1. Click the **+** button just below the message box. 2. Under **Odoo environments**, tick the environments the agent should have access to in this conversation. You can pick more than one. 3. The **Onboard pod** option always stays available — it's the disposable Odoo that ships with every chat. 4. Type your message. The agent will see the selected environments and can call MCP tools against them. You can change the selection at any time mid-chat. The agent only sees the environments that are ticked when it runs the next turn. ## Troubleshooting The XML-RPC endpoint never responded. Common causes: * **Wrong URL** — make sure you can open the same URL in a browser and see the Odoo login page. * **VPN / firewall** — the CodeCobra backend must be able to reach your Odoo instance from the public internet. Self-hosted instances behind a corporate VPN won't work without a tunnel. * **Self-signed certificate** — CodeCobra refuses unverified TLS. Use a real certificate (Let's Encrypt is free). The server replied but Odoo refused the login. Check: * Did you copy the API key without trailing whitespace? * Is the **login** field the user's email/login (not the display name)? * Did you pick the right **database**? * Is the user *Active* in Odoo (not archived)? Your Odoo instance has `list_db = False` in `odoo.conf` (a common production setting). It's not a bug — type the database name in by hand. See [Find the database name](#find-the-database-name) above. Tier (Read / Write / Delete) only controls the **kinds** of operations the agent will attempt. Visibility of specific records is controlled by the linked Odoo user's groups and record rules. Open Odoo as that user and confirm you can see what you expect to see — if you can't see it as that user, the agent won't either. These come straight from Odoo. Read the message carefully — most are self-explanatory (e.g. *"Access Denied"*, *"Database does not exist"*). If you can't make sense of it, copy the full text and [contact support](/support). ## Edit, test, or delete an environment In **Project → Settings → Odoo Environments**: * The **Test** button on each row re-runs authentication against the live server. Useful when an API key has been rotated. * **Edit** lets you change everything except the secret. Leave the API key field blank to keep the existing one — only fill it in to rotate. * **Delete** removes the environment. Any chat that had it selected will lose access on the next message. ## Security notes * Secrets are encrypted with Fernet using a per-deployment key (`ODOO_ENCRYPTION_KEY`). Plaintext keys never appear in logs or API responses — every response shows `has_secret: true` instead of the key itself. * Each environment is scoped to a single project. Members of other projects in the same organization cannot see or use it. * Restricting the agent's footprint inside Odoo is **your** responsibility via Odoo groups, record rules, and a dedicated user. Tier is a coarse on/off for write actions, not a security boundary. ## Next steps Use your new Odoo environment in a real chat. Watch the agent introspect your live data.