# Headscale MCP for AI Agents AI Agent Connect

> Headscale MCP lets you manage your self-hosted mesh network directly through your AI agent. Control users, nodes, and pre-auth keys without switching to a web dashboard or terminal. It turns your AI into a network admin for your private VPN infrastructure.

## Overview
- **Category:** cloud-infrastructure
- **Price:** Free
- **Endpoint:** https://edge.vinkius.com/vk_preview_eY8iPLqKoHS6UDNYs4PXhTC6kItxeqx4gseTYyC6/ai-agent-connect
- **Tags:** vpn, mesh-network, networking, self-hosted, identity-access, infrastructure

## Description

Headscale MCP lets you manage your self-hosted mesh network directly through your AI agent. Managing a private mesh network usually involves a lot of tedious back-and-forth. You have to log into a web console, find the right button to generate a pre-auth key, copy that long string, and then send it to the person who needs it. If you need to move a node to a different user or rename a machine, it's another set of clicks and a different tab. This Connector changes that by letting your AI agent handle the heavy lifting. Instead of hunting for a specific command to revoke access or rename a node, you just tell your agent what needs to happen. It handles the communication with your Headscale instance to keep your infrastructure organized. By using this in the Vinkius catalog, you're moving from manual configuration to conversational management. You get a way to audit your network, manage permissions, and handle onboarding in one place. It's about making your self-hosted VPN feel as easy to manage as a managed service, while keeping your data entirely under your own control.

## Tools

### expire_api_key
expire_api_key invalidates an existing API key. This prevents it from being used for any further requests.

### expire_node
expire_node forces a machine's session to end immediately. This kicks the device off the network for security reasons.

### expire_preauth_key
expire_preauth_key makes a pre-auth key invalid. It ensures the key can no longer be used to register new devices.

### create_preauth_key
create_preauth_key creates a pre-auth key to let new machines join your network. This removes the need for manual approval during onboarding.

### create_user
create_user adds a new administrative user to your Headscale network. You can use this to organize different namespaces for your teams.

### delete_node
delete_node removes a specific machine from your network. Use this to terminate a connection immediately.

### delete_user
delete_user removes a user from your Headscale instance. This revokes their access to all nodes they were associated with.

### disable_route
disable_route turns off a specific network route. This stops traffic from moving through a certain path in your mesh.

### enable_route
enable_route turns on a network route. This allows traffic to flow between your private nodes as needed.

### get_node
get_node fetches the specific details and status for a machine. You can check its IP and connection state quickly.

### list_api_keys
list_api_keys shows a full list of all API keys on your instance. Use this to audit who has access to your network.

### list_nodes
list_nodes views every machine currently connected to your private mesh network. This provides a quick overview of your active fleet.

### list_preauth_keys
list_preauth_keys shows all active pre-auth keys. This helps you track which keys are available for new device registrations.

### list_routes
list_routes views all subnet routes and exit nodes. This shows you exactly how your network traffic is being directed.

### list_users
list_users shows all administrative users in your Headscale setup. This helps you manage permissions across different namespaces.

### rename_node
rename_node changes the display name of a machine. This keeps your network dashboard organized and easy to read.

### create_api_key
create_api_key generates a new API key for your Headscale instance. This allows you to authorize your AI agent to perform actions.

### move_node
move_node changes which user a specific machine belongs to. This is useful for reassigning hardware between different teams.

## Prompt Examples

**Prompt:** 
```
Show me all the nodes currently connected to our Headscale network.
```

**Response:** 
```
I've pulled the current connection list for your Headscale network. Here are the active nodes:

| Name | IP Address | Status |
| :--- | :--- | :--- |
| **web-server-01** | 100.64.0.1 | Online |
| **db-primary** | 100.64.0.2 | Online |
| **dev-laptop-04** | 100.64.0.5 | Online |
| **backup-node** | 100.64.0.10 | Offline |

It looks like most of your infrastructure is up and running.
```

**Prompt:** 
```
I need to onboard a new contractor. Create a user called 'contractors' and give me a new pre-auth key.
```

**Response:** 
```
I've created the new administrative user for you.

*   **User Created:** `contractors`
*   **New Pre-auth Key:** `hs_auth_9x2k_Lp90z_v8m1` 

You can provide this key to the contractor. They can use it to register their machines under the `contractors` namespace.
```

**Prompt:** 
```
A laptop was stolen. Can you kick it off the network right now?
```

**Response:** 
```
I've identified the stolen device as `dev-laptop-old` (Node ID: 12). I am triggering the expiration command now.

**Action Success:** The session for `dev-laptop-old` has been forced to expire. The device is now disconnected from your mesh network and will require re-authentication to rejoin.
```

## Capabilities

### Add administrative namespaces
Create new users to organize different parts of your network.

### Audit connected machines
See every node on your network and check their status in real time.

### Revoke instant access
Force a node to expire or delete it to cut off a connection immediately.

### Issue onboarding keys
Generate pre-auth keys so new devices can join without manual approval.

### Manage traffic flow
Toggle specific network routes to control how data moves between your nodes.

## Use Cases

### Remote Employee Onboarding
A new hire needs VPN access. The admin asks the agent to use create_user and create_preauth_key to get them set up without touching a terminal.

### Security Breach Response
A laptop is reported stolen. The admin tells the agent to expire_node immediately to lock the thief out of the private network.

### Network Migration
A team is moving to a new subnet. The sysadmin asks the agent to list_routes and then enable_route to shift traffic to the new path.

### Audit Cleanup
An admin wants to see who has access. They ask the agent to list_users and list_api_keys to identify and remove old accounts.

## Benefits

- Stop manual key generation. Use create_preauth_key to let devices join automatically without you having to copy-paste strings every time.
- Faster incident response. Use expire_node to kick a compromised machine off your network in seconds instead of hunting for a UI button.
- Better network organization. Use create_user and move_node to group machines into logical namespaces for different teams or projects.
- Easier audits. Use list_nodes and list_routes to get a clear picture of your entire infrastructure status in one chat.
- Granular traffic control. Use enable_route and disable_route to manage how data flows across your mesh network on the fly.

## How It Works

The bottom line is that you turn your AI into a hands-on network administrator for your private VPN.

1. Connect your Headscale API key and server URL to your AI client.
2. Ask your agent to perform actions like listing nodes or creating users.
3. Receive immediate confirmation and updated network status from your Headscale instance.

## Frequently Asked Questions

**Can I use Headscale MCP to manage my own VPN?**
Yes, if you host Headscale, this Connector lets you manage your network via your AI agent.

**Does Headscale MCP work with Tailscale?**
It works with Headscale, which is the open-source alternative to Tailscale.

**How do I kick a device off my network using Headscale MCP?**
Just tell your agent to expire the node or delete it from the network.

**Can I use Headscale MCP to create new users?**
Yes, it can create, list, and delete users for your network.

**Is this Headscale MCP for managing routes?**
Yes, it can enable and disable specific routes across your mesh.

**How do I get a key for a new device?**
Ask your agent to generate a pre-auth key for you.

**Can I move a registered machine from one user to another using the AI?**
Yes. Use the `move_node` tool by providing the Node ID and the target User name. The agent will reassign the machine to the new namespace immediately.

**How do I generate a key for a new server to join the network without manual approval?**
You can use the `create_preauth_key` tool. Specify the user, and optionally set it as reusable or ephemeral. The agent will return a key that can be used with the `tailscale up --login-server` command.

**Is it possible to see the IP addresses and status of all my machines?**
Absolutely. The `list_nodes` tool retrieves a complete list of all registered devices, including their online status, assigned IP addresses, and the users they belong to.