oec.sh

oec.sh MCP server

Let an AI assistant (Claude Code, Claude Desktop, Cursor and other MCP clients) work with your oec.sh organization: look at servers, projects and environments, read an environment's Odoo logs and live metrics, deploy, restart, update modules, take backups and follow a task to its end.

The server adds no powers of its own. Every tool is one or two calls to the oec.sh Public API made with your API key, so the key's type (read only or full access), its scope (organization or one project), your plan, your quotas and the audit log all apply exactly as they do for any other API client.

Requirements: an oec.sh organization on the Starter plan or higher, and an API key from Settings > API Keys in the dashboard. Local mode needs Node.js 22 or newer.

Choose a key

A project-scoped key limits the assistant to one project. Use one whenever the assistant only needs to work on one project.

The server reads the key's type from its prefix and only offers the tools that key can use.

Install: local mode (stdio)

The MCP client starts the server on your computer. Your key stays on your computer and is sent only to api.oec.sh.

Claude Code

claude mcp add oecsh -e OECSH_API_KEY=oec_live_ro_your_key -- npx -y @oecsh/mcp-server

Claude Desktop

Add to claude_desktop_config.json (Settings > Developer > Edit Config), then restart Claude Desktop:

{

"mcpServers": { "oecsh": { "command": "npx", "args": ["-y", "@oecsh/mcp-server"], "env": { "OECSH_API_KEY": "oec_live_ro_your_key" } } } }

Cursor

Add to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

{

"mcpServers": { "oecsh": { "command": "npx", "args": ["-y", "@oecsh/mcp-server"], "env": { "OECSH_API_KEY": "oec_live_ro_your_key" } } } }

Do not commit a file that contains your key.

Settings (local mode)

Hosted mode (streamable HTTP)

https://mcp.oec.sh/mcp. Nothing to install: your client sends your API key with every request in the Authorization header, the server forwards it to the API for that request only, and keeps nothing.

Claude Code:

claude mcp add --transport http oecsh https://mcp.oec.sh/mcp \

--header "Authorization: Bearer oec_live_ro_your_key"

Cursor (mcp.json):

{

"mcpServers": { "oecsh": { "url": "https://mcp.oec.sh/mcp", "headers": { "Authorization": "Bearer oec_live_ro_your_key" } } } }

To turn on opt-in tools in hosted mode, add the header X-OECSH-Allow: destructive (or backup-download, or both, comma separated).

Clients that only connect through OAuth, such as claude.ai web connectors, cannot use the hosted server yet.

The hosted server at mcp.oec.sh passes your address to the API (it is configured with OECSH_MCP_PROXY_SECRET, see below), so the API's block on repeated refused keys counts your address, not the server's shared one. Rate limits are per API key either way.

Tools

Every tool name starts with oecsh_. List tools take limit (1 to 100, default 20) and cursor (the next_cursor of the previous page) and answer with items, count, total, has_more and next_cursor.

Read tools (any key)

Write tools (full-access key; none of them deletes data)

oecsh_create_webhook and oecsh_rotate_webhook_secret return the webhook's signing secret, because the API shows it only once. The secret is then in your conversation transcript, and the tool result says so: if the transcript is shared or stored where others can read it, rotate the secret in the dashboard (Settings > Webhooks) and give the new one to the receiver yourself. Rotating it through the assistant would put the new secret in the transcript too.

Write tools that start work return a task_id; the assistant follows it with oecsh_wait_for_task. Deploy, restart, stop, quick update and the two update tools are marked destructive (they replace running code, take a site offline or overwrite settings), so clients that honour the hint ask before running them; the create tools and start are not.

Opt-in tools

Off unless you turn them on. Each is marked destructive, which is only a hint: most clients then ask for your approval, unless you have auto-approved the tool. Keep these tools out of your client's auto-approve or allow list.

They also take a confirm argument (confirm_environment_name for a restore) that must repeat the resource's name exactly, and the server checks it against the real resource before doing anything. For deleting a webhook or rotating its secret, the name is the webhook's URL. For creating a webhook, testing one, or changing its URL, it is the host the data goes to (for https://hooks.example.com/oec, type hooks.example.com), as the server reads it from the URL: in https://hooks.example.com@other.example/ that is other.example. Changing a webhook's other settings needs no confirm. The assistant is told to ask you for that name, but it can also read names through the list tools, so the argument alone cannot prove that you typed it. So when your client supports MCP elicitation (it can show you a form from the server), the server also asks you to type the name in your client's own prompt, which names the action and the resource, and goes ahead only if you accept and the name matches. Declining, or typing something else, changes nothing. Clients without elicitation, and the hosted server (which keeps no session, so it cannot ask), rely on the confirm argument alone.

Creating, changing and testing webhooks are opt-in because a webhook sends oec.sh data to whatever HTTPS URL it names, and the test sends it at once: text that someone else wrote into a result (an Odoo log line, say) could ask the assistant to point one at their own address. Changing a project's repository or git provider (oecsh_update_project_repository) is opt-in for the same reason: every later deploy runs code from the new repository on your server, and the git provider decides which host your organization's git token is sent to. oecsh_update_project changes everything else about a project. Branch names (branch, default_branch) must be real branch names: ref paths such as refs/..., pull/... or merge-requests/..., bare commit ids and names starting with - are refused, so a deploy cannot pick up code from a fork's pull request.

oecsh_get_backup_download_links answers with a warning: anyone holding a link can download the whole database until it expires, and the links are now in the conversation transcript.

With a read-only key the server offers 24 tools (25 with backup-download). With a full-access key it offers 34, 45 with destructive, and 46 with both opt-ins.

oecsh_restore_backup overwrites an environment's database and files with a completed backup of that same environment (a safety backup of the current data is taken first) and returns a task to follow. The name to type, for a restore or for download links, is the environment's current name; for a stopped or broken environment, which the API does not list, it is the name recorded with the backup (see oecsh_get_backup). Restoring into another environment stays in the dashboard.

Server registration tokens are not available through this server.

Limits

• Every API request counts against your key's rate limit: 120 reads and 20 writes a minute, counted separately.
• Most tools make one or two API requests. oecsh_get_backup_download_links and oecsh_restore_backup make three, and each other confirmed destructive tool two (it reads the resource first to check the name), except creating a webhook or changing its URL, which check the host in the URL given and make one.
• oecsh_get_runtime_logs, oecsh_get_environment_metrics and oecsh_get_server_metrics reach your server on every call, so the API allows 6 of each a minute per environment or server.
• oecsh_wait_for_task polls the task every 5 seconds for the first 30 seconds, then every 10 seconds, and never spends more than a fifth of the read limit the API reports for your key (with a limit of 20 a minute, one poll every 15 seconds). Each call waits up to 50 seconds, since many clients give up on a tool ca