# Headscale MCP > 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. ## Overview - **Category:** cloud-infrastructure - **Price:** Free - **Tags:** vpn, mesh-network, networking, self-hosted, identity-access, infrastructure ## Description 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. ## 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 network. ### 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 instantly. ### 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. ## Prompt Examples **Prompt:** ``` List all nodes currently connected to my Headscale network. ``` **Response:** ``` I've retrieved the node list. You have 4 active nodes: 'web-server-01' (IP: 100.64.0.1), 'db-primary' (IP: 100.64.0.2), and two others. All are currently online except for 'backup-node'. ``` **Prompt:** ``` Create a new user named 'external-contractors' and generate a reusable pre-auth key for them. ``` **Response:** ``` User 'external-contractors' has been created successfully. I have also generated a reusable pre-auth key: `hs_auth_...`. This key can be used to register multiple machines under this user. ``` **Prompt:** ``` Get full details for node ID 12 and then expire its session. ``` **Response:** ``` Inspecting node 12... It's a Linux machine named 'dev-laptop-old'. I have now triggered the `expire_node` action. The machine will be disconnected and will require re-authentication to join the network again. ``` ## Capabilities ### 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. ## Use Cases ### 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. ### 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`. ### 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. ### 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. ## Benefits - 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. ## How It Works The bottom line is that your AI client becomes a hands-free interface for complex network administration tasks. 1. Subscribe to this MCP and provide your Headscale API Key and Server URL. 2. Connect your AI agent (like Cursor or Claude) to the Vinkius marketplace using these credentials. 3. Tell your agent what you need—for example, 'List all users' or 'Expire node XYZ'—and let it execute the command. ## Frequently Asked Questions **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.