---
title: "Nodea MCP server — endpoint, authentication, OAuth discovery, tools | Nodea"
description: "The Nodea MCP server: /mcp endpoint (JSON-RPC 2.0), a Passport token with the mcp:use scope, OAuth discovery and DCR for Claude, ~110 tools across modules, and read-only/destructive annotations."
url: "https://nodea.io/en/api-docs/mcp"
lang: "en"
updated: "2026-11-13"
---

# Nodea MCP server — endpoint, authentication, OAuth discovery, tools | Nodea

> The Nodea MCP server lets AI assistants and coding agents such as Claude, Claude Code, Codex or OpenCode manage monitoring, alerts and infrastructure. Learn the /mcp endpoint, authentication, client setup, tools and action confirmations.

Nodea exposes an **MCP** (Model Context Protocol) server — a standard interface through which AI assistants (such as Claude) and other MCP tools connect to your account and perform actions: check monitoring status, create monitors, manage alerts, servers, DNS, or hosting. Under the hood, MCP uses the same authentication and the same [scopes](https://nodea.io/en/api-docs) as the REST API v1 — a tool gets exactly as much access as the token grants.

This page covers the MCP endpoint, authentication, OAuth discovery for clients like Claude, how tools respect scopes and policies, the tool modules, and the safety annotations. If you are just getting started, begin with the [API introduction](https://nodea.io/en/api-docs/overview).

## Endpoint

The MCP server runs at a single address over **Streamable HTTP** transport (JSON-RPC 2.0 over HTTP POST):

POST https://app.nodea.io/mcp

An MCP client sends JSON-RPC 2.0 requests there (initialize, tools/list, tools/call, and so on). The endpoint is protected by the same Passport guard as API v1, so every request must carry a valid Bearer token.

## Authentication

MCP uses the same **Personal Access Token** as the REST API — you generate it in the panel under API tokens (/app/account/api-tokens) and attach it in the header:

Authorization: Bearer 1|AbCdEf0123456789...

A valid token is enough to connect to the MCP transport. Every tool, however, requires its module scope (e.g. monitoring:read to list websites). A token without the matching scope connects to the server, but the tool call is rejected. Select only the scopes the client needs when you create the token.

MCP clients send the Accept: application/json, text/event-stream header, and with it a request without a valid token gets a 401. If you send requests by hand (e.g. with curl), add the Accept: application/json header; without it the server answers with a redirect to the panel sign-in page.

## OAuth discovery for AI clients (Claude)

Clients like Claude do not require you to paste a token manually — they can **self-onboard** via OAuth. The server publishes discovery metadata compliant with RFC 9728 / RFC 8414:

- GET /.well-known/oauth-protected-resource — protected-resource metadata (points at the authorization server).
- GET /.well-known/oauth-authorization-server — authorization-server metadata (authorize/token endpoints).

When an unauthenticated client hits /mcp, it receives a 401 with a WWW-Authenticate: Bearer … resource\_metadata="…" header that points it to the discovery document — so the client knows where to authorize.

New clients register via **Dynamic Client Registration** (RFC 7591):

POST https://app.nodea.io/oauth/register

Registration creates a public authorization-code OAuth client with PKCE. Only trusted redirect URIs are allowed (the official Claude connector callbacks — https://claude.ai and https://claude.com); the registration endpoint is rate-limited to prevent registration spam. After authorizing, the client receives a token with the mcp:use scope (transport only, no data) and the module scopes approved on the consent screen. The discovery metadata lists only mcp:use because it describes this OAuth path alone.

## How tools respect scopes and policies

Before performing an action, every MCP tool checks the scope, the policies and — for commercial resources — the account permissions:

1. **Token scope** — a monitoring read tool requires monitoring:read, a create/edit tool requires monitoring:write, and a delete tool requires monitoring:delete. No scope = denied (the action never runs).
2. **Ownership policies** — exactly the same as in the panel and REST API. A tool only sees and modifies resources owned by the token holder (and commercial resources of the current customer account); it will not touch someone else's resources even with the right scope.
3. **Customer-account permissions** — ticket, billing, domain, DNS, hosting and VM-backed server tools additionally need the member's permission in the current account (see below).

The same feature flags (Pennant) as the panel also apply — if a module is disabled for your account, its tools are unavailable.

## Customer accounts

Commercial resources (tickets, billing, domains, DNS, hosting, servers backed by a virtual machine) belong to **customer accounts**. Every MCP session acts in **one current account**, resolved exactly as in the REST API: the account the token is pinned to → the X-Account-Id header **of the MCP connection** (set it in your client configuration next to Authorization) → the user's default account → the only membership. HTTP responses carry the X-Account-Id header with the current account.

- The whoami tool returns, among others, default\_account\_id, account (the current account or null) and accounts\[\]; the accounts-list tool (scope account:read) lists the accounts the token may act in.
- Access = token scope **AND** the member's account permission (tickets, invoices, domains/managedomains, products/manageproducts); the owner holds them all. Hosting termination and deleting a VM-backed server are owner-only.
- An invalid account is refused at the connection level: HTTP 403 with a JSON {message, code} body and code account\_forbidden or account\_mismatch.
- Tool denials come back with isError: true and a suffix: (code: account\_permission\_denied, permission: \<flag\>), (code: account\_owner\_required), (code: no\_account\_context), (code: termination\_locked), (code: managed\_by\_whmcs) (deleting a server whose VM WHMCS manages), (code: already\_terminated), (code: service\_suspended) (start/reboot of a VM whose service is suspended in WHMCS or that an administrator suspended), (code: vm\_migrating) (start/stop/reboot of a VM or deleting a server while an administrator moves the VM to another node). A resource outside the current account returns “… not found or not accessible with your permissions.”.

The full description — with a permission table per tool group — is in [Customer accounts — API v1 and MCP](https://nodea.io/en/api-docs/accounts).

## Tool modules

The MCP server exposes about **110 tools**, grouped into modules that mirror the panel's areas:

- **Monitoring** — websites, heartbeats, reports, status-pages.
- **Alerting** — integrations, notification-groups, escalation-policies, shares.
- **Infrastructure** — servers, ssh-keys, dns, vault-devices, ssl-certificates (ssl-certificates-list, ssl-certificate-get — SSL certificates, read-only).
- **Account** — accounts (accounts-list), profile, tickets, billing (Nodea invoices or — for accounts billed in WHMCS — the proforma mirror; every row has a source field: nodea|whmcs; accounts on the new billing also have billing-proformas and billing-payments; free credits — billing-credits, read-only), services (service-upgrade-options, service-upgrade — plan change to a higher plan only), domains, hosting, migrations, work-log (work-log-summary, work-log-entries — the administrators’ work log, read-only).

Each tool carries its own description and argument schema, which the MCP client reads via tools/list. The scope mapping is identical to the REST API: the monitoring module → the monitoring group, alerting → alerting, infrastructure → infra, account → account.

## Annotations: read-only and destructive

Tools are annotated so the client (and the human approving the call) knows what an action does:

- **read-only** — the tool only reads data (lists, details, statuses). Safe to call without extra confirmation.
- **destructive** — the tool performs an irreversible action (deleting a monitor, stopping a VM, terminating hosting, restoring a backup). Such tools **require explicit confirmation**: a confirm: true argument. Without it the call is rejected with a clear message — so an assistant cannot delete a resource "by accident" without deliberate consent. A hosting backup restore (hosting-backup-restore) additionally needs e-mail confirmation: the tool returns status: "pending\_confirmation" and the restore starts only after the customer account owner clicks the e-mailed link (details in the [Hosting](https://nodea.io/en/api-docs/hosting) entry).

## Coding agents: Claude Code, Codex, OpenCode and others

Coding agents running in a terminal or IDE (Claude Code, Codex, OpenCode and other harnesses, i.e. tools that run an AI agent, that support MCP over HTTP with custom headers) connect to the same server with a **personal access token in a header**. OAuth client registration (DCR) accepts only the Claude connector callbacks, so a CLI client cannot complete the OAuth sign-in. You give it a token instead.

1. In the panel: Account → [API tokens](https://app.nodea.io/app/account/api-tokens), create a token with the scopes you need, e.g. infra:read and infra:write for servers, SSH keys and DNS. You can pin the token to one customer account. The token is valid for one year.
2. Keep the token in an environment variable, e.g. NODEA\_TOKEN. Do not commit it to a repository.
3. Add the server to the agent configuration (examples below), then check the connection with the whoami tool.

### Claude Code

claude mcp add --transport http nodea https://app.nodea.io/mcp \\ --header 'Authorization: Bearer ${NODEA\_TOKEN}' claude mcp list # nodea: … ✔ Connected

The single quotes keep the variable name, not the token, in the configuration. Claude Code substitutes the value at startup, so NODEA\_TOKEN must be set in the shell you start it from. The same notation works in a project .mcp.json file; Claude Code asks you to approve a server from that file on first start:

{ "mcpServers": { "nodea": { "type": "http", "url": "https://app.nodea.io/mcp", "headers": { "Authorization": "Bearer ${NODEA\_TOKEN}" } } } }

### Codex

In ~/.codex/config.toml:

\[mcp\_servers.nodea\] url = "https://app.nodea.io/mcp" bearer\_token\_env\_var = "NODEA\_TOKEN"

The command codex mcp add nodea --url https://app.nodea.io/mcp --bearer-token-env-var NODEA\_TOKEN adds the same entry. This configuration works in Codex 0.77 and later. Older versions connected to MCP servers over HTTP only with the experimental rmcp\_client feature turned on, so update Codex first.

### OpenCode

In opencode.json (oauth: false turns off the OAuth sign-in attempt):

{ "$schema": "https://opencode.ai/config.json", "mcp": { "nodea": { "type": "remote", "url": "https://app.nodea.io/mcp", "oauth": false, "headers": { "Authorization": "Bearer {env:NODEA\_TOKEN}" } } } }

Check the connection with opencode mcp list (status connected).

### Other MCP clients

Any client that supports the Streamable HTTP transport and custom headers needs two things: the URL https://app.nodea.io/mcp and the header Authorization: Bearer \<token\>. If you belong to several customer accounts, add the X-Account-Id header or pin the token to an account.

### When the connection fails

- 401: the client did not send the Authorization header, or the token is invalid, expired or revoked. Create a new token in the panel ([API tokens](https://app.nodea.io/app/account/api-tokens)) and replace it in the configuration.
- A redirect to the sign-in page instead of a 401: the request had no Accept header with application/json or text/event-stream (e.g. curl without it). MCP clients send it themselves.
- 429 with "error": "rate\_limited": the client retried with a bad token too many times. Fix the token instead of retrying and wait for the time in the Retry-After header.

The full path "order an instance, add an SSH key, deploy the app" is described in [Deploying from AI coding agents](https://nodea.io/en/api-docs/ai-coding-agents).

## How to connect Claude

In Claude, add an MCP connector pointing at the server URL:

https://app.nodea.io/mcp

Claude will detect the OAuth discovery (/.well-known/oauth-protected-resource), perform client registration and the authorization flow, and you approve the requested scope in the consent screen. Once connected, Claude sees the tool list (tools/list) and can perform actions within the granted scopes — with confirm: true still required for irreversible actions. Alternatively, you can supply a ready-made personal token with the module scopes you need if the client supports a custom Authorization: Bearer header (see "Coding agents").

### What is the MCP server endpoint?

The MCP server runs at https://app.nodea.io/mcp over Streamable HTTP transport (JSON-RPC 2.0 over HTTP POST). It is protected by the same Passport guard as API v1.

### How do I authenticate with MCP?

With the same personal access token as the REST API, in the Authorization: Bearer header. You create the token in the panel under API tokens and select only the module scopes you need. No separate scope is needed just to connect.

### What is the mcp:use scope for?

Only for clients that connect through OAuth (e.g. the Claude connector): they receive it with the token from the authorization. It grants transport access only, no data. Every tool additionally needs its module scope (e.g. monitoring:read) and works within the ownership policies. It does not apply to personal tokens from the panel.

### How do I connect Claude to Nodea MCP?

In Claude, add an MCP connector pointing at https://app.nodea.io/mcp. Claude detects the OAuth discovery (/.well-known/oauth-protected-resource), registers a client via Dynamic Client Registration, and runs the authorization flow where you approve the scope.

### How do I connect Claude Code, Codex or OpenCode?

Create a personal token in the panel (Account → API tokens), keep it in an environment variable and add the server https://app.nodea.io/mcp with the Authorization: Bearer header. For Claude Code: claude mcp add --transport http nodea https://app.nodea.io/mcp --header "Authorization: Bearer $NODEA\_TOKEN". Ready-made Codex and OpenCode configurations are in the "Coding agents" section.

### How many tools does the MCP server have?

About 110 tools across modules that mirror the panel: monitoring (websites, heartbeats, reports, status-pages), alerting, infrastructure (servers, ssh-keys, dns, vault-devices), and account (profile, tickets, billing, domains, hosting, migrations).

### How does MCP protect against accidental resource deletion?

Destructive tools are annotated as such and require an explicit confirm: true argument. Without it the call is rejected, so an assistant cannot delete a resource without deliberate confirmation.

## Related

- [Nodea API v1 — introduction: base URL, tokens, scopes, limits | Nodea](https://nodea.io/en/api-docs/overview)
- [Customer accounts — API v1 and MCP | Nodea Documentation](https://nodea.io/en/api-docs/accounts)
- [Deploying from AI coding agents — Claude Code, Codex, OpenCode and CI | Nodea](https://nodea.io/en/api-docs/ai-coding-agents)

---

Languages: [pl](https://nodea.pl/pl/dokumentacja-api/mcp.md)  
Site index: [llms.txt](https://nodea.io/en/llms.txt)