How to Use the Headscale (Tailscale Alternative) MCP in Claude Code

Q: How do I configure the Headscale (Tailscale Alternative) MCP Server for Claude Code?

Run claude mcp add --transport http -- in your terminal. Make sure you put all your flags before the server name. Verify the installation by running claude mcp list.

Manage your self-hosted VPN directly from the terminal. Claude Code provisions nodes and routes via headless commands.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect Headscale (Tailscale Alternative) MCP to Claude Code

Create your Vinkius account to connect Headscale (Tailscale Alternative) to Claude Code and route execution through our secure gateway. The platform manages server hosting, runtime updates, and security layers. Configuration requires no manual server provisioning.

GDPR Free for Subscribers

Setup Headscale (Tailscale Alternative) with Claude Code

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Claude Code Headscale Automation

Running deployment scripts often requires temporary VPN access for your runners. You can pipe instructions straight into your terminal agent to handle this securely. Before the build starts, it executes `create_preauth_key` to generate a single-use token for the CI container. The runner joins the tailnet, does its job, and disconnects. Your AI client then cleans up the mess by running `expire_node` to kill the session and `delete_node` to scrub the machine from the database. Zero orphaned instances left behind.

Script Subnet Approvals

Managing hundreds of advertised subnets through a CLI is prone to human error. This MCP Server gives your terminal agent the ability to audit and modify routes dynamically. It pulls the current state with `list_routes` and parses the output to find unapproved subnets. You can write a single cron job that tells the agent to approve specific CIDR blocks. It iterates through the pending list and fires `enable_route` for the approved ranges, while actively blocking unauthorized paths with `disable_route`. Your network policy enforces itself.

Reassign Machines Instantly

Moving a server from a staging namespace to production usually breaks routing. Your terminal agent handles this migration without dropping packets. It grabs the exact machine details using `get_node` to verify its current state. Once confirmed, it executes `move_node` to shift the server into the correct user space. It then runs `rename_node` to update the internal DNS record, ensuring your internal services can still resolve the host. The entire migration takes seconds.

Setup guide

Set up Headscale (Tailscale Alternative) MCP in Claude Code

Prerequisites

Claude Code CLI installed (npm install -g @anthropic-ai/claude-code)
Active Vinkius subscription with a valid endpoint token

1

Run the add command

Open your terminal and run the command shown on the right. Replace [YOUR_TOKEN_HERE] with your endpoint token from cloud.vinkius.com. Use --scope user to make it available across all projects.
2

Verify the connection

Start a Claude Code session and type /mcp to list connected servers. You should see headscale-tailscale-alternative-mcp with a green status indicator.
3

Start using tools

Ask Claude Code something like "Check my latest Headscale (Tailscale Alternative) transactions." It will automatically discover and invoke the available Headscale (Tailscale Alternative) tools.

Terminal

claude mcp add --transport http headscale-tailscale-alternative-mcp https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp

Get your connection token →

Prerequisites

Claude Code CLI installed
Active Vinkius subscription with a valid endpoint token

1

Open the config file

Create or edit .mcp.json in your project root for project-level scope, or ~/.claude.json for user-level scope.
2

Add the Headscale (Tailscale Alternative) MCP

Paste the JSON snippet shown on the right into the mcpServers object. Replace [YOUR_TOKEN_HERE] with your endpoint token from cloud.vinkius.com.
3

Restart Claude Code

Start a new Claude Code session. Type /mcp to confirm the server is connected. The tools will be automatically available in your conversation.

.mcp.json

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

Get your connection token →

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.

Why Choose Vinkius

Vinkius connects your tools to AI with real-time monitoring and automatic cost savings — all from one dashboard.

Connect Headscale (Tailscale Alternative) now

Real-time monitoring

Live

visibility into every interaction

Connect your favorite tools to your AI and see exactly what's happening — every request, every response, in real time.

Built-in savings

60%

lower AI costs

Vinkius compresses data between your apps and your AI automatically. Lower bills every month — no configuration required.

Single dashboard

One

place for every integration

Every tool your AI connects to, managed from a single screen. One account, complete control.

Common questions about Headscale (Tailscale Alternative) MCP in Claude Code

Run `claude mcp add --transport http -- ` in your terminal. Make sure you put all your flags before the server name. Verify the installation by running `claude mcp list`.

Yes. You can run the CLI in headless mode during your CI runs. It will execute tools like `list_nodes` or `create_user` as part of your automated deployment pipeline.

Vinkius provides standard HTTP endpoints for these connections. The CLI handles the protocol negotiation automatically, so your terminal session stays connected to the control plane.

You can tell the agent to find users with no active machines. It will run `list_users`, check their associated endpoints, and execute `delete_user` on the empty accounts to keep your database clean.

This server handles highly sensitive material like pre-auth keys, internal IP addresses, and routing policies. Vinkius isolates this execution within a secure V8 environment. Once your headless command finishes and the process exits, the entire memory state is destroyed.

Use it with your favorite AI tools

Connect this server to Cursor, Claude, VS Code, and more.

OpenAI Agents SDK sdk-python

Google ADK sdk-python

Pydantic AI sdk-python

Vercel AI SDK sdk-typescript