• SESSION
  • NODE
  • AUDIT
  • HUMAN

How to revoke node access with your AI client

Connect Headscale to your AI client to manage network security through natural language. You can instantly cut off access for specific devices or expire old sessions.

Ask AI about this page

Short answer

How can I revoke node access using my AI?

You can tell your AI to expire a specific node's session or delete a machine entirely from your Headscale network. This gives you immediate control over your network perimeter without manual CLI commands. Here is how the process works.

Security outcomes

Where every issue lands.

What happens after you give the command.

SESSION

Expired access

The AI kills a specific node's session. The device loses its connection to the network immediately.

NODE

Removed machines

The AI deletes the machine from your Headscale list. This removes the device from your network entirely.

AUDIT

Network visibility

Your AI can check which nodes are currently active. You get a clear view of what is connected before you take action.

HUMAN

Manual oversight

You decide which machines are actually compromised. The AI waits for your confirmation before it deletes anything permanent.

The workflow

What your AI does when a security issue arrives.

The AI acts as your interface to the Headscale API to enforce network policies.

  1. Identify the target

    Your AI looks through your Headscale nodes to find the specific machine or ID you are worried about.

    expire_nodedelete_node

  2. Kill the session

    If you just want to kick a device off the network temporarily, the AI triggers a session expiration.

    expire_node

  3. Remove the device

    For a permanent fix, the AI removes the machine from the network registry.

    delete_node

  4. Confirm status

    The AI verifies the node is no longer active to ensure the command worked.

    expire_nodedelete_node

Try it

Copy these to start.

Direct commands you can use right now.

Starting points

Swap out the bracketed text for your actual node names or IDs.

Headscale Connector

You're all set. Choose your MCP client and follow the setup instructions.

Connector linkhttps://edge.vinkius.com/vk_preview_eY8iPLqKoHS6UDNYs4PXhTC6kItxeqx4gseTYyC6/mcp

Claude Desktop

Follow the steps below to connect in seconds.

  1. 1In Claude Desktop, open Settings → Connectors.
  2. 2Click “Add custom connector” and paste the connector link above as the remote MCP server URL.
  3. 3Click Add and start a new chat — Headscale capabilities are ready to use.
Configuration · claude_desktop_config.jsonCopy
{
  "mcpServers": {
    "headscale-tailscale-alternative-mcp": {
      "url": "https://edge.vinkius.com/vk_preview_eY8iPLqKoHS6UDNYs4PXhTC6kItxeqx4gseTYyC6/mcp"
    }
  }
}
Copy into chat04

  • Expire the session for node [node-id].

  • Delete the machine named [hostname] from my Headscale network.

  • Find all active nodes and tell me which ones I should expire.

  • Remove [node-id] from the network entirely.

  • Claude
  • ChatGPT
  • Cursor
  • VS Code
  • Windsurf
  • Claude Code
  • JetBrains
  • Cline

Start here

Connect Headscale once, then ask.

Just link your Headscale instance to Vinkius. Your credentials stay encrypted, and you can start managing your nodes through any MCP-compatible client immediately.

Connect Headscale to your AI

FAQ

How this task behaves

  • 01

    Can the AI create new nodes for me?

    No. This MCP only provides tools to expire or delete existing nodes.

  • 02

    Will the AI delete my entire network by accident?

    No. The AI only performs actions on specific nodes that you identify in your prompt.

  • 03

    Does the AI handle the Headscale configuration files?

    No. The AI interacts with the Headscale API to manage nodes, not the local configuration files on your machine.

  • 04

    Can I undo a deleted node?

    No. Once the AI uses the delete tool, that node is gone from the Headscale registry.

  • 05

    How does the AI know which node is which?

    The AI reads your current node list to match the names or IDs you provide in your chat.

  • More questions about Headscale? See everything the Headscale Connector can do

Connect Headscale to Claude, Cursor, ChatGPT & more