---
title: "Dedicated servers — API v1 and MCP | Nodea Documentation"
description: "Reference of the Dedicated servers module: REST API v1 endpoints (list, detail), the infra:read scope, the products account permission, MCP tools and curl / JSON-RPC examples."
url: "https://nodea.io/en/api-docs/dedicated-servers"
lang: "en"
updated: "2026-10-14"
---

# Dedicated servers — API v1 and MCP | Nodea Documentation

> Reference of the Dedicated servers module — read-only API v1 endpoints (list, detail), the infra:read scope, visibility within the customer account, MCP tools and examples. Proxmox and BMC credentials are never returned.

The **Dedicated servers** module gives read access to the dedicated servers of a customer account: status, hardware configuration, location, nodeaD agent state and a billing summary. Every dedicated server is priced individually (subscription + setup fee) — ordering goes through the quote request in the panel, not through the API. This document covers the REST API v1 layer (/api/v1/dedicated-servers) and the MCP tools of the module.

## Authentication and scopes

API v1 authenticates with a Passport personal access token in the Authorization: Bearer \<token\> header. The module is read-only:

- infra:read — list and detail of servers.

The module has no Pennant flag. Rate limit: throttle:api-v1 = 240/min per token user. In MCP every tool additionally needs the transport scope mcp:use.

## Customer account, ownership and visibility

Dedicated servers belong to a **customer account** (see [Customer accounts](https://nodea.io/en/api-docs/accounts)). A request acts in the current account (token pin → X-Account-Id header → default account). Besides the token scope the products account permission is required. A server of another account (including another account of the same user) answers 404 — existence is never confirmed.

**Security:** responses never contain Proxmox VE or BMC credentials, admin notes or the internal ids of the hardware, agent host and cluster.

## API v1 — endpoints

MethodPathScopeDescriptionGET/api/v1/dedicated-serversinfra:readServers of the current account (by name), simple pagination: per\_page (1–100, default 20), page. GET/api/v1/dedicated-servers/{id}infra:readOne server.

### Response — DedicatedServerResource

- id, account\_id, name, hostname (nullable), primary\_ip (nullable).
- status — pending | provisioning | active | suspended | cancelled.
- specs — { cpu: string|null, ram\_gb: int|null, disks: \[{ type, size\_gb, count }\] }.
- location — { id, name, country\_code } or null; data\_center — { id, name, code } or null.
- agent — null when no agent host is linked to the server; otherwise { linked, state (provisioned|enrolled|online|offline|revoked|null), last\_seen\_at, version }.
- proxmox\_attached (bool) — whether the server has its own Proxmox VE attached.
- billing — null or { service\_id, status, source (nodea|whmcs|external), currency, price\_cents, billing\_cycle, next\_due\_at }.
- whmcs\_managed (bool), created\_at, updated\_at (ISO8601).

### Error codes

- 401 — missing/invalid token.
- 403 — missing infra:read scope, no account context (no\_account\_context) or missing products permission (account\_permission\_denied).
- 404 — unknown server or a server outside the current account.

## Examples — API

### List servers

curl -s https://app.nodea.io/api/v1/dedicated-servers \\ -H "Authorization: Bearer $NODEA\_TOKEN" \\ -H "Accept: application/json"

### Server detail

curl -s https://app.nodea.io/api/v1/dedicated-servers/42 \\ -H "Authorization: Bearer $NODEA\_TOKEN" \\ -H "Accept: application/json"

## MCP — tools

MCP tools share the authentication, scope and account model of API v1. A server outside the current account returns the same error as a missing one (no cross-tenant enumeration).

ToolScopeModeDescriptiondedicated-servers-listinfra:readread-onlyServers of the current account; page, per\_page (max 50). Fields as in DedicatedServerResource, plus pagination meta. dedicated-server-getinfra:readread-onlyOne server; id (required).

### Example — MCP (JSON-RPC)

{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "dedicated-server-get", "arguments": { "id": 42 } } }

## Related

- [Servers — API v1 and MCP | Nodea Documentation](https://nodea.io/en/api-docs/servers)
- [Customer accounts — API v1 and MCP | Nodea Documentation](https://nodea.io/en/api-docs/accounts)
- [Billing — API v1 and MCP | Nodea Documentation](https://nodea.io/en/api-docs/billing)

---

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