Odoo 19 Futurity MCP invoice lab with request-scoped credentials and a separate API client.
New here? Follow GUIDE.md, or point your coding agent at
.claude/skills/odoo-futurity-plugin/SKILL.md. Change pluginId in
src/manifest.ts before you register: plugin ids are unique across Futurity.
Intentional lab bug — not production-safe: unpaid invoice reads omit both company filtering and company context. Invoices from companies visible to the API user are returned together in a flat list. Odoo access rules still apply.
bun install
cp .env.example .env
bun run keygen
# Add the generated private signing key and ODOO_URL to .env.
bun run devFUTURITY_SIGNING_KEY: Ed25519 private key fromkeygen(required).ODOO_URL: trusted Odoo 19 instance root, e.g.https://company.odoo.com(required).ODOO_DATABASE: optional database name when the hostname does not select it.PUBLIC_URL: externally reachable plugin URL; defaults tohttp://localhost:3000.PORT: listener port, default3000.
Use HTTPS for deployed Odoo and plugin URLs. Never commit .env or private keys.
The Compose setup runs Odoo 19 Community and PostgreSQL 18, with persistent database and Odoo filestore volumes. It does not run the MCP app or seed the lab fixtures.
docker compose up -d
# Open http://localhost:8069 and create a database named odoo.On the database creation screen, set a master password and your administrator login. Install the Invoicing app, then create an API key in your user's account security settings. Configure that key in Futurity (not your login password). For the MCP app running on your host, set:
ODOO_URL=http://localhost:8069
ODOO_DATABASE=odooUse the actual database name if you chose a different one. Create the two-company invoice fixtures separately; this setup does not guarantee the lab's 18-versus-9 result.
docker compose logs -f odoo
docker compose down # Stop containers; retain data.
# docker compose down -v # Destructive: delete all local database and filestore data.This is a local-only setup: Odoo binds to 127.0.0.1, PostgreSQL has no published
port, and the database password in compose.yaml is a development placeholder.
Do not expose this configuration publicly or use it for production.
- Expose the plugin over HTTPS and set
PUBLIC_URLaccordingly. - In Futurity, discover the base URL and register with the public signing key.
- Configure the organization's Odoo API key in the integration credentials.
The signed manifest is at /.well-known/futurity/plugin; its detached signature
is in X-Futurity-Signature. The manifest uses
type: "none", grantType: "api_key", and a required password-style
api_key field. Futurity forwards it as:
X-Plugin-Access-Token: <secret>
Every /mcp request requires this header. Credentials are isolated per async
request; a missing or empty key returns a sanitized 400. Header presence does not
authenticate the caller's platform identity. Odoo validates key validity and user
permissions on API calls. Discovery is public; there is no OAuth token endpoint,
login/password exchange, refresh cache, or API-key preview tool.
{ "offset": 0, "limit": 100 }Reads account.move with move_type = out_invoice, state = posted, and
amount_residual > 0. Returns a flat invoices list with invoice ID/name, customer,
currency, due date (false when absent), and residual amount, alongside
offset, limit, and has_more. No grouping or totals are computed.
offset defaults to 0; limit defaults to 100 (1–200). The read orders by ID and
fetches one extra row to report has_more. When true, request the next page with
offset + limit. Concurrent invoice changes can affect offset pagination.
{
"invoice_id": 42,
"attendee_name": "Alex",
"note": "Call about the outstanding invoice.",
"due_date": "2026-08-14",
"activity_type_id": 4,
"assignee_user_id": 7
}IDs are illustrative: supply an accessible posted customer invoice, a known
activity type, and the intended assignee's Odoo user ID. No IDs are guessed.
The tool validates a real YYYY-MM-DD calendar date, checks the invoice, and calls
account.move activity_schedule on it, so a Billing user needs no access to
ir.model. It returns an integer array of created activity IDs. The attendee
prefix and note are HTML-escaped; note line breaks are preserved. This schedules
an activity, not a calendar attendee invitation or an email.
Odoo permissions govern each operation. The checks and creation are separate transactions, so invoice state can change between them. Calls are never retried; a failed/timeout response may have an uncertain write outcome. Verify existing activities before repeating a write.
The read intentionally supplies neither a company_id domain nor
allowed_company_ids context. It can therefore
mix invoices from multiple companies available in Odoo's effective context.
On Odoo's demo data (two companies, USD and IDR, with repeating invoice numbers)
the read returns 18 invoices; with the fix below it returns 9, with Acme
Corporation on top at $98,375. Other data and API-user access give other counts.
For the company-scope exercise, add this to the unpaid search_read params:
{ "context": { "allowed_company_ids": [1] } }Use [1] only if company 1 is the intended, known accessible company for the
API user; otherwise use the verified company ID. This is instructor guidance,
not an implemented fix or a tool input. The deliberate defect remains in the lab.
src/index.ts configures the app and client, then starts the listener.
Invoice tools are registered before app.listen() and use
client.post({ model, method, params: namedParams, responseSchema, caller: signal }) inside their handlers. Model and method names should be selected by the tool code.
The client posts named JSON parameters to /json/2/<model>/<method> with
Authorization: bearer <API key> and optional X-Odoo-Database. It validates
responses with a supplied Zod schema, rejects redirects, uses a 15-second timeout,
and never retries calls (Odoo methods can mutate data). Errors omit upstream
bodies and tracebacks. Each call is a separate Odoo transaction.
Odoo 19 JSON-2 documentation. External API access on Odoo Online requires a Custom plan. Use a least-privilege bot account and rotate its API key before expiry.
| File | Responsibility |
|---|---|
src/manifest.ts |
Signed discovery manifest configuration |
src/auth.ts |
Request-scoped credential validation |
src/client.ts |
API-key authorization, Odoo 19 JSON-2 transport, and safe errors |
src/index.ts |
Environment configuration, app setup, middleware, tool registration, and listener |
src/tools/invoices.ts |
Paginated unpaid invoice list and follow-up activity creation |
bun run checkThe type check validates TypeScript. No automated test files are currently included; a live Odoo instance and complete Futurity connection remain unverified.