Defined Networking MCP Server

An MCP (Model Context Protocol) server that lets AI coding and DevOps agents manage Defined Networking / Managed Nebula infrastructure.

Use it with Codex, Claude Code, Copilot CLI, VS Code, and other MCP-compatible development tools.

What This Does

Use this server to let an agent inspect and manage Defined Networking infrastructure without hand-writing API calls. It supports common workflows such as:

• designing a Nebula network topology
• provisioning hosts and enrollment codes
• managing roles, firewall rules, tags, routes, and network settings
• auditing configuration and administrative activity
• troubleshooting host connectivity and dnclient state

Quick Start

Install the server:

nvm use
npm install
npm run build

Add it to your MCP client:

{
  "mcpServers": {
    "defined-nebula": {
      "command": "node",
      "args": ["/path/to/defined-mcp/dist/index.js"],
      "env": {
        "DEFINED_API_KEY": "your-api-key-here"
      }
    }
  }
}

For tools that support managed secrets or environment variables, store DEFINED_API_KEY there instead of writing it directly into a config file.

Ask your agent to inspect the account:

"List my Defined Networking networks and summarize the hosts, roles, routes, and tags."

Setup

Prerequisites

• Node.js 24 LTS (24.16.0 or newer within the Node 24 line)
• A Defined Networking account with an API key

This repo includes .nvmrc and .node-version set to Node 24.16.0. npm also uses engine-strict=true, so installs fail on unsupported Node versions instead of silently using an EOL runtime.

Get an API Key

1. Go to admin.defined.net/settings/api-keys
2. Create a new API key with the scopes you need:
   • networks:read — List and view networks
   • hosts:create — Create hosts
   • hosts:read — List and view hosts
   • hosts:update — Update hosts
   • hosts:delete — Delete hosts
   • hosts:enroll — Generate enrollment codes
   • hosts:block — Block/unblock hosts
   • roles:create, roles:read, roles:update, roles:delete — Manage roles
   • tags:create, tags:read, tags:update, tags:delete — Manage tags
   • routes:create, routes:read, routes:delete — Manage routes
   • auditLogs:list — View audit logs

Do not paste API keys directly into shell commands. Prefer an MCP client secret store, a local environment file that is excluded from git, or your shell's secure environment management.

For local development, create an ignored .env.local file:

DEFINED_API_KEY=your-api-key-here

Then load it for the current shell session before running live checks. The command itself does not contain the secret, so it will not be written to shell history:

set -a
. ./.env.local
set +a
npm run test:live

Install From npm

npm install @defined-net/mcp-server

Clone and Build

git clone https://github.com/geoffbelknap/defined-mcp.git
cd defined-mcp
npm install
npm run build

MCP Client Configuration

Use this shape for MCP clients that accept JSON server configuration:

{
  "mcpServers": {
    "defined-nebula": {
      "command": "node",
      "args": ["/path/to/defined-mcp/dist/index.js"],
      "env": {
        "DEFINED_API_KEY": "your-api-key-here"
      }
    }
  }
}

If you installed the package globally, use "command": "defined-mcp" and omit args.

Environment Variables

Variable	Required	Default	Description
DEFINED_API_KEY	Yes	—	Your Defined Networking API key
DEFINED_API_URL	No	https://api.defined.net	API base URL (for custom deployments)

Tool Behavior

• Tools return structured results with operation names, resource IDs, side effects, warnings, and API error details.
• Mutating tools execute when called. Pass dryRun: true when you want the server to return a preview plan instead.
• Enrollment-code tools can return credential material. Treat their results like secrets.

Capabilities

The MCP targets the current non-deprecated Defined Networking API surface from the official OpenAPI description, including hosts, roles, routes, tags, audit logs, networks, and downloads. Deprecated v1 endpoints are intentionally omitted when a current replacement exists.

Tools

Network Management

• list-networks — List all Nebula overlay networks
• get-network — Get detailed network information
• update-network — Update network name, description, and lighthouse relay behavior
• delete-network — Delete an empty network
• add-network-cidr — Add an IPv4 CIDR to an IPv6-only network

Host Management

• list-hosts — List hosts with filtering (by network, role, type, status)
• get-host — Get host details
• create-host — Create a new host (lighthouse, relay, or regular)
• update-host — Update host configuration
• delete-host — Remove a host from the network
• block-host — Block a host (revoke network access)
• unblock-host — Restore a blocked host
• debug-host — Send host debug commands such as log streaming, tunnel inspection, certificate inspection, lighthouse queries, and stack traces

Enrollment

• create-host-and-enrollment-code — Create a host + enrollment code in one step
• create-enrollment-code — Generate enrollment code for existing host

Roles & Firewall

• list-roles — List all roles
• get-role — Get role details with firewall rules
• create-role — Create a new role
• update-role — Update role configuration
• delete-role — Remove a role
• get-firewall-rules — Get inbound firewall rules for a role
• update-firewall-rules — Replace firewall rules for a role (supports role-based and tag-based rules)

Tags

• list-tags — List all tags (key:value pairs for fine-grained access control)
• get-tag — Get tag details
• create-tag — Create a new tag (e.g. env:production, region:us-east)
• update-tag — Update a tag
• delete-tag — Remove a tag

Routes (Unsafe Routes)

• list-routes — List routes extending access to non-overlay subnets
• get-route — Get route details
• create-route — Create a route through a gateway host
• update-route — Update route name, router host, routable CIDRs, and firewall rules
• delete-route — Remove a route

Audit & Compliance

• list-audit-logs — Search audit logs by target

Downloads

• list-downloads — List available DNClient software downloads for all platforms

Resources

• nebula://networks/{networkID} — Network configuration data
• nebula://hosts/{hostID} — Host configuration data
• nebula://roles/{roleID} — Role and firewall rule data

Prompts

• design-network — Interactive network topology design
• provision-host — Step-by-step host provisioning guide
• audit-security — Security posture audit
• troubleshoot-connectivity — Debug connectivity between hosts

Usage Examples

Design a Network

"Design a Nebula overlay network for my development team of 15 engineers with separate roles for web servers, databases, and developer endpoints."

The agent will use the design-network prompt to plan the topology, then execute the creation using the tools.

Provision a Host

"Add a new lighthouse named 'us-east-lighthouse' to my network with static address 203.0.113.1:4242"

Security Audit

"Audit the security posture of my Nebula network. Check for overly permissive firewall rules and blocked hosts."

Troubleshoot

"I can't connect from host-ABC to host-XYZ on port 443. Help me figure out why."

Architecture

┌─────────────────────────────────────────────────┐
│  AI Agent (Codex / Claude Code / VS Code / etc.)│
├─────────────────────────────────────────────────┤
│  MCP Protocol (stdio / JSON-RPC 2.0)            │
├─────────────────────────────────────────────────┤
│  defined-nebula MCP Server                      │
│  ┌─────────┐ ┌──────────┐ ┌───────────┐        │
│  │  Tools  │ │Resources │ │  Prompts  │        │
│  └────┬────┘ └────┬─────┘ └───────────┘        │
│       │           │                              │
│  ┌────┴───────────┴────┐                        │
│  │   Defined API Client │                        │
│  └──────────┬──────────┘                        │
├─────────────┼───────────────────────────────────┤
│  HTTPS + Bearer Token                            │
├─────────────┼───────────────────────────────────┤
│  Defined Networking API (api.defined.net)        │
├─────────────┼───────────────────────────────────┤
│  Nebula Overlay Network                          │
│  ┌───┐ ┌───┐ ┌───┐ ┌───┐ ┌───┐                │
│  │ L │ │ H │ │ H │ │ R │ │ H │                │
│  └───┘ └───┘ └───┘ └───┘ └───┘                │
│  L=Lighthouse  H=Host  R=Relay                  │
└─────────────────────────────────────────────────┘

Development

nvm use
npm install
npm run dev    # Watch mode
npm run build  # Production build
npm start      # Run the server

Tests and Security Checks

npm test              # Build and run non-mutating dry-run smoke tests
npm run test:live     # Run read-only live API checks plus dry-run mutation checks
npm run security:audit

npm run test:live requires DEFINED_API_KEY. It performs read-only API calls and explicit dry-run mutation checks only.

The default npm test target is safe for CI environments without real Defined credentials because it uses dry-run mutation plans and a placeholder API key.

License

MIT