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

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 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.

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...

To connect to the MCP transport, the token must carry the mcp:use scope. Important: mcp:use grants transport access only — on its own it unlocks no data. Every tool additionally requires the appropriate module scope (e.g. monitoring:read to list websites). A token with only mcp:use can connect to the server, but any attempt to use a tool without the matching scope is rejected.

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 that — for data access — must carry the appropriate module scopes alongside mcp:use.

How tools respect scopes and policies

Before performing an action, every MCP tool checks two things:

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; it will not touch someone else's resources even with the right scope.

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

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.
• Account — profile, tickets, billing, domains, hosting, migrations.

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.

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 Access Token (with mcp:use plus the module scopes you need) if the client supports pasting a Bearer token manually.