@byteder/mcp

Model Context Protocol server for the Byteder Cloud API. Lets Claude Desktop, Cursor, and other MCP clients manage your projects, instances, SSH keys, activity logs, billing, and product catalog over a single API key. Full feature parity with the REST API.

Install

No install needed — point your MCP client at npx:

npx -y @byteder/mcp

Or install globally:

npm install -g @byteder/mcp
byteder-mcp

Requires Node.js 18+.

Configure

The server reads two environment variables:

| Variable | Required | Default | Notes | |---|---|---|---| | BYTEDER_API_KEY | yes | — | Your bdr_live_… API key from dash.byteder.com → Settings → API Keys | | BYTEDER_API_URL | no | https://developer.byteder.com | Override for staging or self-hosted |

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %AppData%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "byteder": {
      "command": "npx",
      "args": ["-y", "@byteder/mcp"],
      "env": {
        "BYTEDER_API_KEY": "bdr_live_..."
      }
    }
  }
}

Restart Claude Desktop. The Byteder tools will appear in the tool picker.

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "byteder": {
      "command": "npx",
      "args": ["-y", "@byteder/mcp"],
      "env": { "BYTEDER_API_KEY": "bdr_live_..." }
    }
  }
}

MCP Inspector (debugging)

BYTEDER_API_KEY=bdr_live_... npx @modelcontextprotocol/inspector npx -y @byteder/mcp

Tools

43 tools covering the full REST surface. Tools marked 🔒 confirm require a literal confirm: true argument — Claude will ask you to approve before sending.

Projects

| Tool | Purpose | |---|---| | list_projects | Every project this key can access | | get_project | One project by ID | | create_project | Create a PERSONAL or ORGANIZATION project | | update_project | Rename or edit organization details | | delete_project 🔒 | Soft-delete (fails if active instances remain) |

Instances — read & metadata

| Tool | Purpose | |---|---| | list_instances | All VMs in a project | | get_instance | One VM (incl. credentials) | | update_instance | Rename / re-describe (no VM impact) |

Instances — lifecycle

| Tool | Purpose | |---|---| | create_instance 🔒 | Provision a new VM (charges credits) | | start_instance | Power on | | stop_instance | Graceful ACPI shutdown | | restart_instance | Reboot | | force_stop_instance 🔒 | Hard kill — risk of FS corruption | | rebuild_instance 🔒 | Reinstall OS — wipes disk | | delete_instance 🔒 | Tear down | | upgrade_instance_plan 🔒 | Resize to a larger plan (charges + restart) |

Instances — VPC networking

| Tool | Purpose | |---|---| | attach_instance_vpc | Attach the instance to a VPC subnet (adds a private NIC + private IP). Pass reboot: true to apply now — 🔒 confirm required only when reboot: true | | detach_instance_vpc | Remove the instance's VPC private NIC. 🔒 confirm required only when reboot: true |

Instances — billing & credentials

| Tool | Purpose | |---|---| | change_billing_period | Schedule period change (next cycle) | | cancel_pending_billing_period | Revert a scheduled change | | update_instance_ssh_key | Replace SSH key (restarts VM) | | update_instance_password | Reset root password (restarts VM) |

SSH keys (account-scoped)

| Tool | Purpose | |---|---| | list_ssh_keys | All saved keys | | add_ssh_key | Save a new public key | | delete_ssh_key | Remove a saved key (does not affect deployed VMs) |

VPC (private networking)

| Tool | Purpose | |---|---| | list_vpcs | All VPCs in a project | | get_vpc | One VPC (subnets, attached instances, peerings) | | create_vpc 🔒 | Provision a VPC (SDN VLAN + VNet + subnet) | | delete_vpc 🔒 | Delete a VPC (fails if instances attached) | | list_vpc_subnets | Subnets in a VPC | | create_vpc_subnet | Add a subnet (CIDR within the VPC range) | | delete_vpc_subnet 🔒 | Delete a subnet (fails if instances attached) | | list_vpc_peerings | Peerings for a VPC | | request_vpc_peering | Request peering with another VPC | | accept_vpc_peering | Accept an incoming peering request | | reject_vpc_peering | Reject an incoming peering request | | delete_vpc_peering 🔒 | Remove a peering |

To connect an existing instance to a VPC, use attach_instance_vpc (above). VPC selection at creation time is also available via the vpc_id / subnet_id fields on create_instance.

Catalog (no API key required for read)

| Tool | Purpose | |---|---| | list_catalog_regions | Available deploy regions | | list_catalog_tiers | Service tiers | | list_catalog_datacenters | Datacenters in a region (codenames for create_instance) | | list_catalog_plans | Server plans + pricing per period | | list_catalog_os | OS images |

Audit

| Tool | Purpose | |---|---| | get_recent_logs | Activity log (cursor-paginated) |

After creating an instance

Provisioning is asynchronous. create_instance returns immediately with status CREATING; the instance becomes RUNNING roughly a minute later, once the sync job observes it. Lifecycle calls — upgrade_instance_plan, resize_instance, convert_to_custom — are rejected while it is still CREATING, so poll get_instance until the status flips rather than acting straight after create.

If it reports RUNNING but you cannot reach it — SSH refused, no ping — the guest occasionally boots without working networking. Call restart_instance once and wait for it to come back; that clears it.

If it is still unreachable after that single restart, the problem is not the boot. Stop and report it instead of restarting in a loop — repeated reboots will not fix a networking or placement fault, and each one costs the customer more downtime on a VM they are already being billed for.

Safety: the confirm: true gate

Destructive tools (delete, rebuild, force-stop, create-instance, upgrade-plan, create/delete-VPC, delete-subnet/peering) require a literal confirm: true field. A few tools (attach_instance_vpc, detach_instance_vpc) require it only when reboot: true, since the reboot causes downtime. The model can't satisfy this from a vague natural-language request — it has to explicitly include confirm: true in the tool call, which Claude Desktop surfaces in its approval prompt. This protects against:

• Accidental destructive calls from ambiguous prompts
• Prompt injection attacks asking the agent to "delete all my VMs"
• Tool-call retries on transient failures double-firing

If a destructive call fails with Refusing to … : 'confirm' must be exactly true, that's the gate working as designed.

Permissions

The server uses your API key's existing scopes. If a tool returns "API key requires scope X", grant the missing scope to the key in the dashboard.

License

MIT