API Reference

Internal API documentation for odoo-rust-mcp developers.

MCP Protocol Methods

initialize

Called by clients to establish a session.

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",
    "clientInfo": {
      "name": "cursor",
      "version": "1.0.0"
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-03-26",
    "serverInfo": {
      "name": "odoo-rust-mcp",
      "version": "0.5.0"
    },
    "capabilities": {
      "tools": {},
      "prompts": {},
      "resources": {}
    }
  }
}

tools/list

List available tools.

Request:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "odoo_search",
        "description": "Search for Odoo records...",
        "inputSchema": { ... }
      }
    ]
  }
}

tools/call

Execute a tool.

Request:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "odoo_search_read",
    "arguments": {
      "instance": "production",
      "model": "res.partner",
      "domain": [["is_company", "=", true]],
      "fields": ["name", "email"],
      "limit": 10
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"records\":[...],\"count\":10}"
      }
    ]
  }
}

prompts/list

List available prompts.

Response:

{
  "result": {
    "prompts": [
      {
        "name": "odoo_common_models",
        "description": "List of commonly used Odoo models"
      }
    ]
  }
}

prompts/get

Get prompt content.

Request:

{
  "method": "prompts/get",
  "params": {
    "name": "odoo_domain_filters"
  }
}

resources/list

List Odoo resources.

Response:

{
  "result": {
    "resources": [
      { "uri": "odoo://instances", "name": "Odoo Instances" },
      { "uri": "odoo://production/models", "name": "Models" }
    ]
  }
}

Operation Types

Internal operation types mapped from tools.json via op.type:

MCP HTTP Endpoints

When running in HTTP transport mode (--transport http):

MCP Streamable HTTP (per MCP spec)

Legacy Endpoints

Public Endpoints (no auth)

Health Check Response

{
  "service": "odoo-rust-mcp",
  "status": "ok"
}

Config UI API (Port 3008)

Authentication

The Config UI uses Bearer token authentication. Token is stored in localStorage as mcp_config_token and sent via the Authorization: Bearer {token} header.

Public Endpoints (no auth required)

Protected Endpoints (require auth)

Instance connection test

POST /api/config/instances/{name}/test

Tests the connection to a named Odoo instance by loading its config from instances.json, creating a client, and calling health_check() (which runs a lightweight search_count on ir.model). The test runs server-side so it bypasses browser CORS restrictions.

Response (success):

{ "ok": true, "latency_ms": 142 }

Response (failure):

{ "ok": false, "error": "Connection refused (os error 111)" }

Static Files and Documentation

The documentation route is discovered at startup by find_docs_dir(), which searches for docs/book/ relative to the working directory and executable path. If the docs have not been built (mdbook build), the /docs/ route is simply not registered — the server starts normally.

Config Server Health Check Response

{
  "service": "odoo-rust-mcp-config",
  "status": "ok"
}

Odoo API Mapping

JSON-2 API (v19+)

POST /json/2/{db}/{model}/{method}
Authorization: Bearer {api_key}
Content-Type: application/json

JSON-RPC API (<v19)

POST /jsonrpc
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "call",
  "params": {
    "service": "object",
    "method": "execute_kw",
    "args": [db, uid, password, model, method, args, kwargs]
  }
}

Error Codes