Skip to main content
Glama
Sign In
Headscale MCP connector

Headscale MCP connector

by si-essence
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

headscale_policy

DestructiveIdempotent

Validate, compare, retrieve, or replace a Headscale tailnet policy, with dry-run previews and explicit confirmation for writes.

Instructions

headscale_policy calls the policy toolset on a self-hosted Headscale server (4 actions). Authorization is Bearer. Writes need confirm set to the boolean true and HEADSCALE_ALLOW_WRITES=true. Omit confirm for a dry-run preview that does not send the write. Warnings: A bad policy can lock all nodes out of the tailnet. Actions: check_policy: POST /api/v1/policy/check. Validate a policy. Headscale does not save it. diff: GET /api/v1/policy. Compare a proposed policy with the saved policy. Sends only the policy read. get_policy: GET /api/v1/policy. Get the current policy. set_policy: PUT /api/v1/policy. Replace the tailnet policy.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "action": "<action>"
    },
    "name": "headscale_policy"
  }
}

Input Schema

NameRequiredDescriptionDefault
bodyNoJSON body for the Headscale operation. Secrets are redacted in previews.
queryNoOpenAPI query parameters.
actionYesHeadscale operation to call.
paramsNoOpenAPI path parameters, such as nodeId or id.
confirmNoSet to the boolean true to execute the write. Omit this field for a dry-run preview. false and the string true are rejected.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.3/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations (destructive=true, idempotent=true, openWorld=true), the description discloses the Bearer auth requirement, the dual gate on writes (confirm must be the boolean true AND HEADSCALE_ALLOW_WRITES=true), and that omitting confirm yields a dry-run that does not send the write. It also warns that a bad policy can lock all nodes out of the tailnet and clarifies check_policy does not persist anything.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the resource, auth and write-gating rules before the action list, and each action entry is a single compact line. There is minor redundancy between the upfront confirm/dry-run statement and the schema's confirm description, but nothing is wasted for a four-action dispatcher.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, multi-action dispatcher with nested objects and no output schema, it covers auth, write preconditions, dry-run behavior and the safety warning. The main residual gap is what the read/validate actions actually return (policy shape, validation result), which the agent must infer.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents body, query, params, action and confirm. The description restates the confirm semantics and adds the action-to-endpoint mapping, but adds no new meaning for the generic body/query/params containers (e.g. which fields belong in a policy body), so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the resource explicitly (the policy toolset on a self-hosted Headscale server) and enumerates all four actions with their HTTP methods and paths. An agent can distinguish this from siblings headscale_meta, headscale_nodes and headscale_users purely by resource scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Each action carries a one-line purpose (validate, compare, read, replace), which tells the agent which action to pick for a given intent, and the confirm/omit-confirm rule gives clear execution-vs-dry-run guidance. It stops short of stating exclusions or when to prefer a sibling tool, so not a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools