Headscale MCP. Manage your self-hosted private mesh network.

Q: How do I use the Headscale MCP to see all connected machines?

Run listnodes. This tool pulls a complete inventory of every machine currently attached to your network, giving you a real-time picture of your infrastructure.

Q: Can I instantly revoke access using the Headscale MCP?

Yes. You can use expirenode on a specific device or expireapikey if an administrator key is compromised, ensuring immediate disconnection.

Q: Does the Headscale MCP help with user segmentation?

Absolutely. Use createuser to establish separate segments and then use movenode to place machines into specific, restricted namespaces.

Q: How do I check what network routes are active in Headscale?

You run the listroutes tool. This gives you a clear overview of all subnet paths and exit points that your mesh uses for traffic.

Headscale Headscale (Tailscale Alternative) MCP connects your self-hosted private mesh network to your AI agent. Manage users, nodes, and security keys directly through conversation. You can list connected machines, create new user accounts, enforce node expirations, and control network routes without touching the command line.

Claude

ChatGPT

Cursor

Gemini

Windsurf

VS Code

JetBrains

Vercel

See Vinkius in Action

Give Claude and any AI agent real-world access

Manage Users

Create, list, or delete user accounts (namespaces) to segment and organize different parts of your network.

Monitor Nodes

List all connected machines, get specific node details, rename them, move them between users, or force their session expiration.

Control Access Keys

Generate new API keys and pre-auth keys; list existing credentials, then expire any key or node to revoke access immediately.

Adjust Network Routes

Inspect network routes across the mesh and toggle specific routes on or off to manage data flow.

Ask an AI about this

Waiting for input…

AI Agent

What AI agents can do with Headscale (Tailscale Alternative) with 18 Tools

Use these tools to programmatically handle every aspect of your private mesh network, from user creation and node listing to route adjustments and key management.

Make your AI actually useful.

Add this MCP to Claude, Cursor, or Windsurf and your AI stops guessing. It gets real tools to look things up, take action, and handle the stuff you keep doing by hand.

Start using Headscale (Tailscale Alternative) MCP

Create Api Key

Generates a brand new API key for administrative use.

Create Preauth Key

Creates a reusable or temporary pre-authentication key to allow nodes to join the...

Create User

Establishes a new administrative user segment within Headscale.

Delete Node

Removes a specific machine from the entire Headscale network roster.

Delete User

Permanently deletes an administrative user account and its associated segment.

Disable Route

Turns off a specific network route, stopping traffic flow on that path.

Enable Route

Activates a previously disabled network route to restore data flow across the mesh.

Expire Api Key

Immediately invalidates an existing API key, requiring it to be regenerated.

Expire Node

Forces a connected machine's session to expire, disconnecting it from the network...

Expire Preauth Key

Invalidates an existing pre-authentication key before its expiration date.

Get Node

Retrieves full, detailed information about a single specified node.

List Api Keys

Provides a list of all current API keys configured on the system.

List Nodes

Pulls a complete inventory of every machine currently connected to the network.

List Preauth Keys

Lists all existing pre-authentication keys and their status.

List Routes

Displays a comprehensive list of all subnet routes and exit points in the mesh.

List Users

Lists every user account segment configured within Headscale.

Move Node

Transfers a node from one user namespace to another administrative user segment.

Rename Node

Changes the visible name of a connected machine within Headscale's records.

Security and governance baked right in.

Pick your AI client below to get set up. Just create a Vinkius account, subscribe, and you're instantly up and running. We handle the entire backend infrastructure, delivering out-of-the-box support for HTTPS Streamable, SSE, and OAuth2—zero messy routing required.

Claude AI

Open Claude Settings

Go to claude.ai, click your profile icon, then navigate to Customize → Connectors.

Add Custom Connector

Click the "+" button and select Add custom connector. Paste your Vinkius endpoint URL:

https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp

Replace [YOUR_TOKEN_HERE] with your token from cloud.vinkius.com. For OAuth-protected servers, expand Advanced settings to add credentials.

Start a conversation

Open a new chat. The Headscale integration is available immediately — no restart needed.

Antigravity

Configure Agent Environment

Open your Antigravity agent's workspace configuration or mcp-servers.json file.

Bind the Endpoint

Add the Vinkius endpoint URL to your agent's MCP connections list:

"mcp_servers": {
  "headscale-tailscale-alternative": {
    "serverUrl": "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
  }
}

Provide your secure token in place of [YOUR_TOKEN_HERE] to ensure your agent requests are authenticated.

Execute

Start your Antigravity session. The agent will autonomously discover and utilize the Headscale tools with full Vinkius guardrails applied.

Headscale MCP is compatible with VS Code

VS Code Copilot

⚡

One-Click Install (Recommended)

In your Vinkius Dashboard, simply click the Add to VS Code button for this server. We'll automatically configure your local workspace.

Or configure manually

Open MCP Settings

Open VS Code, press Ctrl/Cmd + Shift + P, and search for GitHub Copilot: MCP Servers.

Add Server Config

Add the Vinkius endpoint configuration to your mcp-servers.json file:

"headscale-tailscale-alternative": {
  "url": "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
}

Ensure you replace [YOUR_TOKEN_HERE] with your token from cloud.vinkius.com.

LangChain

Install Dependencies

Install the LangChain MCP adapters for your environment:

pip install langchain-mcp-adapters

Connect the Server

Use the SSEClient in LangChain to connect to the Vinkius managed endpoint:

from langchain_mcp_adapters.client import SSEClient

# Connect to Vinkius
client = SSEClient(url="https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp")
tools = client.get_tools()

CrewAI

Define the Tool

Load the Vinkius MCP tools into your CrewAI agents:

from crewai import Agent
from mcp_crewai import MCPTool

# Connect securely to Vinkius
vinkius_tools = MCPTool(url="https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp")

# Assign to Agent
researcher = Agent(
    role='Data Researcher',
    tools=vinkius_tools.get_all()
)

Execute Task

Run your CrewAI process. The agent will autonomously route tasks to the Vinkius managed server.

Choose How to Get Started

Build a custom MCP for your own tools, or connect a ready-made integration from our catalog.

Build Your Own

Turn any API into an MCP. Import a spec, define Agent Skills, or deploy with MCPFusion.

Import from OpenAPI, Swagger, or YAML specs
Create Agent Skills with progressive disclosure
Deploy to edge with MCPFusion framework
Built in DLP, auth, and compliance on each call
Real time usage dashboard and cost metering
Publish to catalog or keep private

Start building

Make Your AI Do More

Start with Headscale (Tailscale Alternative), then connect any of our 5,200+ other servers whenever your AI needs more. One click, no limits.

Use this MCP plus 5,200+ others, all in one place
Add new capabilities to your AI anytime you want
Connections are secured and governed automatically
Track usage and costs across all your servers
Works with Claude, ChatGPT, Cursor, and more
New servers added to the catalog weekly

Independent Platform Disclaimer: Vinkius is an independent platform and is not affiliated with, endorsed by, sponsored by, verified by, or otherwise authorized by Headscale. All third-party trademarks, logos, and brand names are the property of their respective owners. Their use on this website is strictly for informational purposes to identify service compatibility and interoperability.

VINKIUS CLOUD

Cloud Hosted

Managed infra

V8 Isolated

Sandboxed per request

Zero-Trust Proxy

No stored credentials

DLP Enforced

Policy on each call

GDPR Compliant

EU data residency

Token Compression

~60% cost reduction

Your data is protected. See how we built it.

Managing network access used to feel like a series of terminal commands.

Today, managing node lifecycles or revoking access means jumping between dashboards and running specific CLI commands. You have to remember the exact syntax for `list_users` versus how you delete them, making routine audits slow and error-prone. It’s a manual checklist of copy/paste operations.

With this MCP, all that complexity is abstracted away. Your agent handles the execution flow—you just ask it what needs to change. You get conversational control over infrastructure that used to require deep SSH knowledge.

The Headscale MCP gives you complete node and user lifecycle management.

You no longer need to remember the difference between `delete_user` (which removes a whole segment) and simply running `get_node` (which just reads data). You can tell your agent, 'Audit the access for this node, list its user, and if it's old, expire it.'

This MCP shifts network administration from rote command execution to high-level policy enforcement. It’s immediate control.

Support 24/7 support@vinkius.com ↗

Security Vinkius Trust Center ↗

SLA Service Level Agreement ↗

Report Listing Send Report ↗

vpn

mesh-network

networking

self-hosted

identity-access

infrastructure

What Headscale MCP does for your AI

This MCP gives you full administrative power over a private Headscale network—the self-hosted alternative to Tailscale's control server. Your AI agent acts like an embedded network administrator, letting you manage your mesh network entirely through natural language prompts. Need to audit who is on the network? You can list all connected machines and pull detailed metadata for specific nodes.

If a contractor leaves, you don't need SSH access; you simply tell your agent to expire that node or user account instantly. The platform lets you generate reusable or temporary pre-auth keys for onboarding new devices. It also gives you granular control over network traffic by listing and enabling or disabling specific routes.

All of this infrastructure management is available through Vinkius, the central catalog where you connect your preferred AI client.

Built · Hosted · Managed by Vinkius Headscale MCP - Manage Private Mesh Network Access

Server ID 019e38a6-9ba2-7344-bfae-a989c9a9c77d

Vinkius Inspector

Compliance Grade A+

Score 100/100

Report View Report ↗

Benefits of connecting Headscale MCP

Audit node status instantly. Instead of logging into the controller and running list_nodes, you ask your agent to provide a full inventory, getting real-time details on every connected machine.

Enforce security boundaries with precision. If a contractor's laptop is compromised, instead of waiting for it to time out, you can use expire_node via your agent to instantly revoke all access and disconnect the device.

Streamline user onboarding. You no longer need manual approvals for temporary devices; simply ask your agent to create_preauth_key, allowing new nodes to join automatically under a specific user segment.

Maintain network structure with ease. Using the MCP, you can list_routes and then tell your agent to enable_route or disable_route for quick traffic adjustments without touching any configuration files.

Centralized control over credentials. Need to audit which keys are active? You can use list_api_keys and even call expire_api_key immediately if a key is found to be unused or compromised.

Headscale MCP use cases

01 01

Revoking Access After Termination

A project manager needs to terminate access for an external team. Instead of manually tracking and revoking credentials, they prompt their agent: 'Expire all nodes associated with the billing department.' The agent handles listing users, then using expire_node across multiple machines.

02 02

Debugging a Broken Connection

A DevOps engineer notices an important subnet is unreachable. They ask their agent to check the network flow and confirm if routes are active. The agent uses list_routes and confirms which route needs to be fixed using enable_route.

03 03

Auditing Network Segments

A security officer needs to verify that a specific machine is correctly placed under the 'production' namespace. They ask their agent to run list_nodes, find the device, and then use move_node to confirm its placement.

04 04

Setting up Temporary Access

A team needs a temporary connection for a vendor testing a new feature. The engineer uses the agent to first create_user, then generate limited access using create_preauth_key, ensuring the access is time-bound.

Headscale MCP tradeoffs

What to watch out for, and the recommended way to handle each one.

Assuming API key management is simple

Avoid

Trying to manually track which temporary keys are active and when they expire by checking a spreadsheet.

Instead

Use your agent with the MCP. First, run list_preauth_keys to see what's active, then use expire_preauth_key to kill access immediately if necessary.

Managing nodes manually

Avoid

Logging into the web UI or CLI multiple times just to rename a machine or check its user segment.

Instead

Use your agent's rename_node and move_node tools. You can tell it, 'Rename this node from old-dev and move it to the finance namespace,' all in one prompt.

Ignoring network segmentation needs

Avoid

Allowing general access because it's easier than setting up rules for different teams.

Instead

First, use create_user and delete_user to define clear organizational boundaries. Then manage traffic flow using list_routes and toggling routes as needed.

When to use Headscale MCP

Use this MCP if your primary need is granular, programmatic control over the lifecycle of a self-hosted mesh network. You need an AI agent to function as a central point for tasks like expiring sessions (expire_node), managing user boundaries (create_user), or adjusting traffic flow (enable_route). Don't use this if you just need general file storage or basic messaging; those require different types of MCPs. If your issue is simply needing a list of nodes, the list_nodes tool solves that immediately. However, if you also need to audit who can delete users (a separate concern), you might need additional authentication-focused tools in addition to this one.

Frequently asked questions about Headscale MCP

How do I use the Headscale MCP to see all connected machines? +

Run list_nodes. This tool pulls a complete inventory of every machine currently attached to your network, giving you a real-time picture of your infrastructure.

Can I instantly revoke access using the Headscale MCP? +

Yes. You can use expire_node on a specific device or expire_api_key if an administrator key is compromised, ensuring immediate disconnection.

Does the Headscale MCP help with user segmentation? +

Absolutely. Use create_user to establish separate segments and then use move_node to place machines into specific, restricted namespaces.

What is the difference between a pre-auth key and an API key in Headscale? +

A pre-auth key is used for initial machine registration; you manage these with create_preauth_key and list them using list_preauth_keys. An API key is for administrative access.

How do I check what network routes are active in Headscale? +

You run the list_routes tool. This gives you a clear overview of all subnet paths and exit points that your mesh uses for traffic.

Give Claude and any AI agent real-world access

What AI agents can do with Headscale (Tailscale Alternative) with 18 Tools

Create Api Key

Generates a brand new API key for administrative use.

Create Preauth Key

Creates a reusable or temporary pre-authentication key to allow nodes to join the...

Create User

Establishes a new administrative user segment within Headscale.

Delete Node

Removes a specific machine from the entire Headscale network roster.

Delete User

Permanently deletes an administrative user account and its associated segment.

Disable Route

Turns off a specific network route, stopping traffic flow on that path.

Enable Route

Activates a previously disabled network route to restore data flow across the mesh.

Expire Api Key

Immediately invalidates an existing API key, requiring it to be regenerated.

Expire Node

Forces a connected machine's session to expire, disconnecting it from the network...

Expire Preauth Key

Invalidates an existing pre-authentication key before its expiration date.

Get Node

Retrieves full, detailed information about a single specified node.

List Api Keys

Provides a list of all current API keys configured on the system.

List Nodes

Pulls a complete inventory of every machine currently connected to the network.

List Preauth Keys

Lists all existing pre-authentication keys and their status.

List Routes

Displays a comprehensive list of all subnet routes and exit points in the mesh.

List Users

Lists every user account segment configured within Headscale.

Move Node

Transfers a node from one user namespace to another administrative user segment.

Rename Node

Changes the visible name of a connected machine within Headscale's records.

Security and governance baked right in.

Claude AI

Open Claude Settings

Add Custom Connector

Start a conversation

Claude Code

Open your terminal

Add the MCP Server

Start coding

Cursor

One-Click Install (Recommended)

Open Cursor Settings

Add New Server

Use in Composer

Antigravity

Configure Agent Environment

Bind the Endpoint

Execute

VS Code Copilot

One-Click Install (Recommended)

Open MCP Settings

Add Server Config

Windsurf

One-Click Install (Recommended)

Open Windsurf Settings

Add Server Endpoint

LangChain

Install Dependencies

Connect the Server

CrewAI

Define the Tool

Execute Task

Choose How to Get Started

Build Your Own

Make Your AI Do More

Managing network access used to feel like a series of terminal commands.

The Headscale MCP gives you complete node and user lifecycle management.

vpn

mesh-network

networking

self-hosted

identity-access