@yawlabs/tailscale-mcp 0.15.0 → 0.17.0

package/README.md

@@ -5,7 +5,7 @@
 [![GitHub stars](https://img.shields.io/github/stars/YawLabs/tailscale-mcp)](https://github.com/YawLabs/tailscale-mcp/stargazers)
 [![Release](https://img.shields.io/badge/release-local-blue)](./release.sh)
 
-**Ask your agent questions about your tailnet and have it act on the answers.** 89 admin-API tools + 4 optional local-CLI diagnostics + 4 resources covering the full [Tailscale v2 API](https://tailscale.com/api). Backed by 700+ unit tests and an opt-in live-tailnet integration suite.
+**Ask your agent questions about your tailnet and have it act on the answers.** 94 admin-API tools + 6 optional local-CLI diagnostics + 4 resources spanning the [Tailscale v2 API](https://tailscale.com/api) — devices, ACLs, DNS, keys and trust credentials, users, invites, webhooks, log streaming, posture, services, and organization tailnets. Backed by 1100+ unit tests and an opt-in live-tailnet integration suite.
 
 Built and maintained by [Yaw Labs](https://yaw.sh).
 
@@ -31,7 +31,7 @@ If all you need is one endpoint in a CI job, use `curl` — we even have a [CLI
 
 Reasonable question. Both have their place. Where this MCP is better:
 
-- **Full admin API coverage.** The `tailscale` CLI is scoped to the node it runs on. Admin concerns — ACLs, users, invites, webhooks, log streaming, posture integrations, auth keys, OAuth clients, and federated identities — live in the v2 HTTP API. You'd be shelling out to `curl` anyway.
+- **Broad admin API coverage.** The `tailscale` CLI is scoped to the node it runs on. Admin concerns — ACLs, users, invites, webhooks, log streaming, posture integrations, auth keys, OAuth clients, and federated identities — live in the v2 HTTP API. You'd be shelling out to `curl` anyway.
 - **Typed tool surface, not string parsing.** Every tool has a Zod-validated input schema and a structured response. No brittle `tailscale status --json | jq` pipelines that break when the schema evolves.
 - **Cross-client, no user rewriting.** A Claude Code skill only loads in Claude Code. An MCP server works in Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, and anything else that speaks MCP. Version bumps ship through `npx` — users don't re-author their skill when Tailscale adds an endpoint.
 - **Safe-by-default writes.** Every tool declares `readOnlyHint` / `destructiveHint` / `idempotentHint` so clients can skip confirmation on reads and require it on mutations. A skill that shells out to the CLI can't express that.
@@ -54,7 +54,7 @@ Issues and PRs are triaged. File one if something is off — [github.com/YawLabs
 
 **1. Set your API key**
 
-Get an API key from [Tailscale Admin Console > Settings > Keys](https://login.tailscale.com/admin/settings/keys) and add it to your shell profile (`~/.bashrc`, `~/.zshrc`, or Windows system environment variables):
+Get an API key from [Tailscale Admin Console > Settings > Keys](https://console.tailscale.com/admin/settings/keys) and add it to your shell profile (`~/.bashrc`, `~/.zshrc`, or Windows system environment variables):
 
 ```bash
 export TAILSCALE_API_KEY="tskey-api-..."
@@ -104,7 +104,7 @@ That's it. Now ask your agent:
 
 ## Too many tools? Subset them.
 
-89 tools is a lot. If you've already got a dozen MCP servers and your client is feeling heavy, trim what this one exposes. Three knobs, combinable:
+94 tools is a lot. If you've already got a dozen MCP servers and your client is feeling heavy, trim what this one exposes. Three knobs, combinable:
 
 ### Option 1: `TAILSCALE_PROFILE` (preset, easiest)
 
@@ -118,8 +118,8 @@ That's it. Now ask your agent:
 ```
 
 - **`minimal`** (20 tools) — `status`, `devices`, `audit`. Observe the tailnet, read the audit log.
-- **`core`** (47 tools) — adds `acl`, `dns`, `keys`, `users`. The day-to-day admin surface.
-- **`full`** (89 tools, default) — everything. Same as omitting the env var.
+- **`core`** (49 tools) — adds `acl`, `dns`, `keys`, `users`. The day-to-day admin surface.
+- **`full`** (94 tools, default) — everything. Same as omitting the env var.
 
 ### Option 2: `TAILSCALE_TOOLS` (explicit group list)
 
@@ -181,12 +181,14 @@ Recommended pattern for mcph users: set `TAILSCALE_PROFILE=core` (or narrower) i
 
 **API key (simplest):** Set `TAILSCALE_API_KEY` in your shell or MCP config.
 
-**OAuth (scoped access):** For fine-grained permissions, set `TAILSCALE_OAUTH_CLIENT_ID` and `TAILSCALE_OAUTH_CLIENT_SECRET` instead. Create an OAuth client at [Tailscale Admin Console > Settings > OAuth](https://login.tailscale.com/admin/settings/oauth).
+**OAuth (scoped access):** For fine-grained permissions, set `TAILSCALE_OAUTH_CLIENT_ID` and `TAILSCALE_OAUTH_CLIENT_SECRET` instead. Create an OAuth client at [Tailscale Admin Console > Settings > OAuth](https://console.tailscale.com/admin/settings/oauth).
 
 The server checks for an API key first, then falls back to OAuth. If neither is set, tools return a clear error telling you what to configure — the server still starts, so your MCP client doesn't loop restarting.
 
 **Tailnet:** Uses your default tailnet automatically. Set `TAILSCALE_TAILNET` to specify one explicitly.
 
+**`TAILSCALE_OAUTH_TAILNET`** — target an **API-only tailnet** (one created by `tailscale_create_org_tailnet`). Those tailnets are not reachable with a plain client-credentials exchange: you authenticate with an OAuth client belonging to the *creating* tailnet (`all` scope) and the target rides on the token request. Set this to the new tailnet's id. Deliberately separate from `TAILSCALE_TAILNET` so the default token exchange is unchanged for everyone else. If you set this, leave `TAILSCALE_TAILNET` unset (or `-`) so tool requests follow the token — pointing the two at different tailnets makes every tailnet-scoped tool return 403, and the server warns about it at startup.
+
 ## Reliability and debugging
 
 **429 retry (built-in).** API responses with HTTP 429 are retried up to 3 times, honoring the `Retry-After` header (both seconds-integer and HTTP-date forms). Falls back to exponential backoff with jitter, capped at 30s per wait. No env var needed — this is on by default. Workflows like "rotate every key older than 90 days" no longer fail mid-loop on Tailscale's per-tenant rate limits.
@@ -206,13 +208,15 @@ The server checks for an API key first, then falls back to OAuth. If neither is
 
 **`TAILSCALE_EXTRA_WEBHOOK_EVENTS=eventA,eventB`** — opt-in escape hatch for webhook event types Tailscale ships after the latest release of this package. The webhook tools validate `subscriptions` against a strict static catalog so typos and stale event names fail fast with a clear error; if you need a brand-new event before the catalog catches up, list it here (comma-separated) and the schema will accept it. Please also [open an issue](https://github.com/YawLabs/tailscale-mcp/issues) so the static list catches up.
 
+**`TAILSCALE_EXTRA_POSTURE_PROVIDERS=providerA,providerB`** — the same escape hatch for device-posture integration providers. `tailscale_create_posture_integration` validates `provider` against a static list (`falcon`, `fleet`, `huntress`, `intune`, `jamfpro`, `kandji`, `kolide`, `sentinelone`); if Tailscale adds one before this package catches up, list it here rather than waiting for a release. This field used to be a closed enum, which made a newly-supported provider *uncreatable* rather than merely unvalidated.
+
 **Friendlier error messages.** JSON error bodies of the form `{"message":"..."}` or `{"error":"..."}` are unwrapped before display, so you see the prose explanation instead of raw JSON. 401s still get the full multi-line auth-error formatter (with the Windows env-var hint when applicable).
 
 ## Local CLI integration (opt-in)
 
 Most tools talk to the Tailscale v2 admin API — they describe **the tailnet**. Sometimes you want to ask about **this machine's** view: is it actually connected? What DERP region is it on? How far is `my-laptop` from here? Those answers come from the local `tailscale` binary, not the admin API.
 
-Set `TAILSCALE_LOCAL_CLI=1` (in your shell or `.mcp.json` `env` block) to add four read-only diagnostic tools:
+Set `TAILSCALE_LOCAL_CLI=1` (in your shell or `.mcp.json` `env` block) to add six read-only diagnostic tools:
 
 | Tool | Equivalent CLI command | Use it for |
 |---|---|---|
@@ -223,7 +227,7 @@ Set `TAILSCALE_LOCAL_CLI=1` (in your shell or `.mcp.json` `env` block) to add fo
 
 Requirements: the `tailscale` binary must be in `PATH`. If it's installed somewhere unusual, set `TAILSCALE_BINARY` to its absolute path. The MCP server doesn't need root to run these — they're all diagnostic, not state-mutating. Operations that would need elevation (`tailscale up`, `set --advertise-routes`, `lock sign`) are deliberately not exposed.
 
-When opt-in is on, the startup banner reflects it: `@yawlabs/tailscale-mcp v0.13.3 ready (93 tools, local-cli=on)` — the 4 local CLI tools are additive on top of the default 89.
+When opt-in is on, the startup banner reflects it: `@yawlabs/tailscale-mcp v0.13.3 ready (100 tools, local-cli=on)` — the 6 local CLI tools are additive on top of the default 94.
 
 ## Resources (4)
 
@@ -236,7 +240,7 @@ MCP Resources expose read-only data clients can browse without a tool call.
 | ACL Policy | `tailscale://tailnet/acl` | Full ACL policy (HuJSON preserved) |
 | DNS Config | `tailscale://tailnet/dns` | Nameservers, search paths, split DNS, MagicDNS |
 
-## Tools (89 + 4 opt-in)
+## Tools (94 + 6 opt-in)
 
 <details>
 <summary><strong>Status</strong> (1 tool)</summary>
@@ -304,7 +308,7 @@ MCP Resources expose read-only data clients can browse without a tool call.
 </details>
 
 <details>
-<summary><strong>Keys / Trust Credentials</strong> (5 tools) — covers auth keys, OAuth clients, and federated identities</summary>
+<summary><strong>Keys / Trust Credentials</strong> (7 tools) — covers auth keys, OAuth clients, federated identities, and OAuth apps</summary>
 
 | Tool | Description |
 |------|-------------|
@@ -313,6 +317,8 @@ MCP Resources expose read-only data clients can browse without a tool call.
 | `tailscale_create_key` | Create an auth key, OAuth client (`keyType=client`), or federated identity (`keyType=federated`) |
 | `tailscale_delete_key` | Delete a key |
 | `tailscale_update_key` | Update a key's description, scopes, tags, or federated claim settings |
+| `tailscale_create_oauth_app` | Create an OAuth App for third-party device provisioning (Tailscale alpha) |
+| `tailscale_get_oauth_app` | Get an OAuth App's name, redirect URIs, and scopes |
 
 </details>
 
@@ -387,6 +393,23 @@ MCP Resources expose read-only data clients can browse without a tool call.
 
 </details>
 
+<details>
+<summary><strong>Organization Tailnets</strong> (3 tools) — API-only tailnets; OAuth authentication required</summary>
+
+Create and tear down whole tailnets programmatically — useful for per-agent sandboxes,
+per-tenant isolation, and ephemeral CI environments. Unlike every other group here these
+endpoints live under `/organizations`, authenticate **only** with an OAuth client (the
+`tailnets` scope to create, `all` to then reach the tailnet), and produce tailnets that are
+not managed in the admin console. Set `TAILSCALE_OAUTH_TAILNET` to operate on one.
+
+| Tool | Description |
+|------|-------------|
+| `tailscale_list_org_tailnets` | List the organization's tailnets (paginated via `limit` / `cursor`) |
+| `tailscale_create_org_tailnet` | Create an API-only tailnet; returns its OAuth client secret **once** |
+| `tailscale_delete_tailnet` | Delete a tailnet (the configured one, or an explicit `tailnet`) — irreversible; requires `confirmTailnet` to match |
+
+</details>
+
 <details>
 <summary><strong>Log Streaming</strong> (7 tools)</summary>
 
@@ -440,7 +463,7 @@ MCP Resources expose read-only data clients can browse without a tool call.
 </details>
 
 <details>
-<summary><strong>Local CLI</strong> (4 tools, opt-in) — see <a href="#local-cli-integration-opt-in">Local CLI integration</a></summary>
+<summary><strong>Local CLI</strong> (6 tools, opt-in) — see <a href="#local-cli-integration-opt-in">Local CLI integration</a></summary>
 
 | Tool | Description |
 |------|-------------|
@@ -448,6 +471,8 @@ MCP Resources expose read-only data clients can browse without a tool call.
 | `tailscale_ping` | Latency probe to another tailnet node from this machine |
 | `tailscale_netcheck` | NAT type, DERP latency map, IPv4/IPv6 support diagnostics |
 | `tailscale_local_version` | Local `tailscale` binary version |
+| `tailscale_local_whoami` | Which user and device this machine is authenticated as (needs tailscale >= 1.102.1) |
+| `tailscale_local_service_list` | Tailscale Services visible to *this* node (needs tailscale >= 1.102.1) |
 
 </details>
 
@@ -511,7 +536,15 @@ This shows a read-only banner in the Tailscale Admin Console pointing to your re
 
 ## Running on oam.js (optional)
 
-[oam.js](https://oamjs.org) runs this server unmodified. Verified against oam 0.8.2: full MCP handshake, all 89 tools, all 4 resources, identical error messages, and a clean stdout protocol stream — from the shipped bundle *and* straight from the TypeScript source with no build step.
+[oam.js](https://oamjs.org) runs this server unmodified. Verified against oam 0.9.0: full MCP handshake, all 94 tools, all 4 resources, identical error messages, and a clean stdout protocol stream — from the shipped bundle *and* straight from the TypeScript source with no build step.
+
+**oam 0.9.0 is the minimum.** Older releases ran `child_process.execFile` arguments through a shell, re-splitting them on whitespace and executing shell metacharacters inside an argument. This server shells out to the `tailscale` binary across its local-CLI tools, so that was a reachable bug rather than a theoretical one. The launcher enforces the floor: given an older oam it falls back to Node and says so on stderr, and `TAILSCALE_MCP_RUNTIME=oam` turns that into a hard error.
+
+### Sandboxing (opt-in)
+
+Set `TAILSCALE_MCP_SANDBOX=1` to run under oam's `--permission` model: network restricted to `api.tailscale.com` and `login.tailscale.com`, filesystem denied. Child-process stays granted because the local-CLI tools shell out to the `tailscale` binary, which is also why `PATH` remains in the environment allow-list.
+
+It is opt-in rather than default because a wrong grant does not fail loudly. oam denies a non-granted environment variable by making it **absent** from `process.env` rather than throwing, so an under-granted `TAILSCALE_API_KEY` reads as "unauthenticated" rather than "denied". The env allow-list in the launcher is derived from what the shipped bundle actually reads -- if you add a new `process.env` lookup, extend that list with it.
 
 ```jsonc
 {

package/bin/tailscale-mcp.mjs

@@ -22,19 +22,46 @@
  * For an MCP host config, point straight at oam and skip this file:
  *   { "command": "oam", "args": ["run", "<abs>/dist/index.js"] }
  *
+ * THE `--permission` SANDBOX (oam 0.9.0+, opt-in)
+ * `TAILSCALE_MCP_SANDBOX=1` runs the server under oam's permission model:
+ * network limited to the control-plane hosts, filesystem denied.
+ *
+ * Child-process is granted unconditionally because the local-CLI tools shell out
+ * to the `tailscale` binary; that is also why PATH stays in the env grant, since
+ * resolving the binary needs it.
+ *
+ * Opt-in, not default, because a denied environment variable is ABSENT from
+ * process.env rather than throwing -- an under-granted TAILSCALE_API_KEY reads as
+ * "unauthenticated" rather than "denied". The env list is derived from the
+ * shipped bundle; keep it in step.
+ *
+ * MINIMUM OAM VERSION
+ * 0.9.0. Below it `child_process.execFile` ran its arguments through a SHELL,
+ * `exec` accepted `timeout` and ignored it, `spawnSync` truncated at
+ * `maxBuffer` while reporting success, and `stdio: 'inherit'`/`'ignore'` both
+ * behaved as `'pipe'`. This server shells out to a CLI on its
+ * main paths, so those were reachable bugs rather than theoretical ones: an
+ * argument containing shell metacharacters was re-split and executed.
+ * An older oam is not an error: the launcher falls back to Node and says so on
+ * stderr. Pinning the floor here is what makes that fallback automatic.
+ *
  * SELECTION
  *   TAILSCALE_MCP_RUNTIME=oam    require oam; fail loudly if it is missing
  *   TAILSCALE_MCP_RUNTIME=node   never use oam
  *   TAILSCALE_MCP_RUNTIME=auto   prefer oam, silently fall back (default)
+ *   TAILSCALE_MCP_SANDBOX=1      run oam under --permission (oam 0.9.0+)
  *   OAM_BIN=/path/to/oam     explicit binary, checked before any discovery
  */
 
-import { spawn } from "node:child_process";
+import { execFileSync, spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { constants, homedir } from "node:os";
 import { delimiter, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
+/** Oldest oam whose `child_process` matches Node. See MINIMUM OAM VERSION above. */
+const OAM_MIN = [0, 9, 0];
+
 // Two forms, deliberately. `import()` on Windows REJECTS a bare `C:\...` path
 // with ERR_UNSUPPORTED_ESM_URL_SCHEME (it reads `c:` as a protocol), so the
 // in-process fallback must use the file:// URL. spawn() needs a real path.
@@ -83,6 +110,66 @@ function findOam() {
   return null;
 }
 
+/**
+ * `oam --version` -> [major, minor, patch], or null when it cannot be read.
+ * A pre-release suffix (0.9.0-rc.1) truncates to its base version.
+ */
+function oamVersion(cmd) {
+  try {
+    const out = execFileSync(cmd, ["--version"], {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    const m = /(\d+)\.(\d+)\.(\d+)/.exec(out);
+    return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+  } catch {
+    // Not executable, wrong arch, or deleted since the stat. Caller degrades.
+    return null;
+  }
+}
+
+/** True when `v` is at least `min`, comparing major/minor/patch in order. */
+function atLeast(v, min) {
+  if (!v) return false;
+  for (let i = 0; i < min.length; i++) {
+    if (v[i] > min[i]) return true;
+    if (v[i] < min[i]) return false;
+  }
+  return true;
+}
+
+/**
+ * The `--permission` grant list, or [] when the sandbox is not requested.
+ *
+ * These are oam's PROCESS-level flags: they belong before the `run` subcommand,
+ * not after it. `oam run --permission file.js` is rejected outright, which is a
+ * good failure but only because it is loud -- ordering here is load-bearing.
+ *
+ * Net grants prefix-match `host` for fetch and `host:port` for sockets.
+ * A denied environment variable is ABSENT from process.env rather than throwing,
+ * so the env list below is derived from what the bundle actually reads; trimming
+ * it produces silent misbehaviour, not a clear denial.
+ */
+function sandboxFlags() {
+  if (process.env.TAILSCALE_MCP_SANDBOX !== "1") return [];
+
+  const hosts = ["api.tailscale.com","login.tailscale.com"];
+
+  const netFlag = `--allow-net=${hosts.join(",")}`;
+
+  // Keep alphabetised and in sync with every env var the bundle reads -- a
+  // missing entry is ABSENT from process.env rather than an error, so the
+  // symptom is silent misbehaviour. TAILSCALE_LOCAL_CLI was missing here, which
+  // meant the local-CLI tool group silently failed to register under the
+  // sandbox even though --allow-child-process is granted below precisely so
+  // those tools can shell out.
+  const env = ["PATH","TAILSCALE_API_KEY","TAILSCALE_BINARY","TAILSCALE_DEBUG","TAILSCALE_EXTRA_POSTURE_PROVIDERS","TAILSCALE_EXTRA_WEBHOOK_EVENTS","TAILSCALE_LOCAL_CLI","TAILSCALE_MAX_CONCURRENT","TAILSCALE_OAUTH_CLIENT_ID","TAILSCALE_OAUTH_CLIENT_SECRET","TAILSCALE_OAUTH_TAILNET","TAILSCALE_PROFILE","TAILSCALE_READONLY","TAILSCALE_REQUEST_BUDGET_MS","TAILSCALE_RETRY_BASE_DELAY_MS","TAILSCALE_TAILNET","TAILSCALE_TOOLS"];
+
+  const flags = ["--permission", netFlag, `--allow-env=${env.join(",")}`];
+  flags.push("--allow-child-process");
+  return flags;
+}
+
 /** Run the server in THIS process. The zero-overhead fallback. */
 async function runInProcess() {
   // A server may gate its bootstrap on being the process ENTRY POINT --
@@ -120,10 +207,29 @@ if (mode === "node") {
       process.exit(1);
     }
     await runInProcess();
+  } else if (!atLeast(oamVersion(oam), OAM_MIN)) {
+    // Discovery itself stays stat-only; this is the first subprocess, and it
+    // runs only once we have already decided to spawn oam anyway. Measured 26ms
+    // median (n=12, windows-arm64), paid once per MCP session.
+    const min = OAM_MIN.join(".");
+    if (mode === "oam") {
+      const { writeSync } = await import("node:fs");
+      writeSync(
+        2,
+        `tailscale-mcp: TAILSCALE_MCP_RUNTIME=oam but ${oam} is older than oam ${min}.\n` +
+          `Run \`oam self-update\`, or use TAILSCALE_MCP_RUNTIME=node.\n`,
+      );
+      process.exit(1);
+    }
+    // auto: an old oam is a reason to prefer Node, not to fail. Say so, because
+    // a silent downgrade is how someone keeps running an oam they meant to
+    // update. stderr is safe -- MCP frames travel on stdout.
+    process.stderr.write(`tailscale-mcp: oam at ${oam} is older than ${min}; using Node instead.\n`);
+    await runInProcess();
   } else {
     // `--` separates oam's own flags from the script's argv, so `tailscale-mcp
     // --version` and any host-supplied flags survive the hop unchanged.
-    const child = spawn(oam, ["run", SERVER_ENTRY, "--", ...process.argv.slice(2)], {
+    const child = spawn(oam, [...sandboxFlags(), "run", SERVER_ENTRY, "--", ...process.argv.slice(2)], {
       // inherit keeps the SAME fds, so MCP's newline-delimited JSON framing on
       // stdin/stdout is untouched and the host's stdin-close still reaches the
       // server's shutdown path.

package/dist/index.js

@@ -30993,6 +30993,10 @@ function getAuthConfig() {
     `No Tailscale credentials configured. Set TAILSCALE_API_KEY, or set both TAILSCALE_OAUTH_CLIENT_ID and TAILSCALE_OAUTH_CLIENT_SECRET.${hint}`
   );
 }
+function getOAuthTailnet() {
+  const raw = process.env.TAILSCALE_OAUTH_TAILNET?.trim();
+  return raw ? raw : void 0;
+}
 async function getOAuthAccessToken(clientId, clientSecret) {
   if (oauthToken && Date.now() < oauthToken.expires_at - 6e4) {
     return oauthToken.access_token;
@@ -31002,7 +31006,9 @@ async function getOAuthAccessToken(clientId, clientSecret) {
   }
   oauthRefreshPromise = (async () => {
     try {
-      const res = await fetch("https://api.tailscale.com/api/v2/oauth/token", {
+      const oauthTailnet = getOAuthTailnet();
+      const tokenUrl = oauthTailnet ? `https://api.tailscale.com/api/v2/oauth/token?tailnet=${encodeURIComponent(oauthTailnet)}` : "https://api.tailscale.com/api/v2/oauth/token";
+      const res = await fetch(tokenUrl, {
         method: "POST",
         headers: { "Content-Type": "application/x-www-form-urlencoded" },
         body: new URLSearchParams({
@@ -31014,7 +31020,7 @@ async function getOAuthAccessToken(clientId, clientSecret) {
       });
       if (!res.ok) {
         const body = await res.text();
-        const guidance = res.status === 401 || res.status === 403 ? " Verify TAILSCALE_OAUTH_CLIENT_ID and TAILSCALE_OAUTH_CLIENT_SECRET, and that the client has the scopes your tools need (https://login.tailscale.com/admin/settings/oauth)." : "";
+        const guidance = res.status === 401 || res.status === 403 ? " Verify TAILSCALE_OAUTH_CLIENT_ID and TAILSCALE_OAUTH_CLIENT_SECRET, and that the client has the scopes your tools need (https://console.tailscale.com/admin/settings/oauth)." + (oauthTailnet ? ` Targeting tailnet "${oauthTailnet}" via TAILSCALE_OAUTH_TAILNET -- that requires an OAuth client from the CREATING tailnet with the 'all' scope.` : "") : "";
         throw new Error(`OAuth token exchange failed (${res.status}): ${body}.${guidance}`);
       }
       const data = await res.json();
@@ -31080,7 +31086,7 @@ function formatAuthError(status, apiBody) {
       "  2. Set TAILSCALE_API_KEY as a Windows user environment variable (System Properties > Environment Variables)"
     );
   }
-  const link = status === 401 ? "Generate a new key at: https://login.tailscale.com/admin/settings/keys" : usingOAuth ? "Adjust the OAuth client scopes at: https://login.tailscale.com/admin/settings/oauth" : "Adjust the API key permissions at: https://login.tailscale.com/admin/settings/keys";
+  const link = status === 401 ? "Generate a new key at: https://console.tailscale.com/admin/settings/keys" : usingOAuth ? "Adjust the OAuth client scopes at: https://console.tailscale.com/admin/settings/oauth" : "Adjust the API key permissions at: https://console.tailscale.com/admin/settings/keys";
   lines.push("", link);
   if (apiBody) {
     lines.push("", `API response: ${apiBody}`);
@@ -32605,6 +32611,58 @@ var keyTools = [
       }
       return apiPut(`/tailnet/${getTailnet()}/keys/${encPath(input.keyId)}`, body);
     }
+  },
+  // --- OAuth Apps (device provisioning) ---
+  //
+  // ALPHA upstream. Distinct from the OAuth *clients* handled by
+  // tailscale_create_key above: an OAuth client is a machine credential you
+  // hold, whereas an OAuth App is a three-legged authorization-code app that
+  // lets a THIRD PARTY enroll one device into your tailnet after a user
+  // consents. The only scope it takes today is `auth_keys:create:once`, which
+  // mints exactly one auth key per authorization and returns no refresh token
+  // -- re-authorization is required per device by design.
+  {
+    name: "tailscale_create_oauth_app",
+    description: "Create an OAuth App for device provisioning (Tailscale alpha). Lets a third-party application enroll a device into your tailnet via the authorization-code flow, after a user consents. Returns the app's client secret -- save it immediately, it cannot be retrieved again.\n\nSECURITY: the response body contains a long-lived credential verbatim. MCP clients commonly persist tool responses to logs and conversation transcripts; treat this response as sensitive.\n\nThe supported scope is 'auth_keys:create:once' (one auth key per authorization, no refresh token). Distinct from tailscale_create_key with keyType='client', which mints a machine-to-machine OAuth client instead.",
+    annotations: {
+      title: "Create OAuth app",
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      name: external_exports.string().min(1).describe("Human-readable name for the OAuth app, shown on the consent screen"),
+      redirectUris: external_exports.array(external_exports.url()).min(1).describe("Allowed redirect URIs for the authorization-code flow (e.g. ['https://example.com/callback'])"),
+      scopes: external_exports.array(external_exports.string()).min(1).describe("Scopes to grant. Currently 'auth_keys:create:once' is the supported value."),
+      allowedNodeAttributes: external_exports.array(external_exports.string()).optional().describe("Optional node attributes the app may request when provisioning a device")
+    }),
+    handler: async (input) => {
+      const body = {
+        name: input.name,
+        redirectUris: input.redirectUris,
+        scopes: input.scopes
+      };
+      if (input.allowedNodeAttributes !== void 0) body.allowedNodeAttributes = input.allowedNodeAttributes;
+      return apiPost(`/tailnet/${getTailnet()}/oauth-apps`, body);
+    }
+  },
+  {
+    name: "tailscale_get_oauth_app",
+    description: "Get an OAuth App's configuration (name, redirect URIs, scopes) by its app ID. Use this to verify an app was registered as intended. The client secret is not returned -- it is only available at creation time.",
+    annotations: {
+      title: "Get OAuth app",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      appId: external_exports.string().min(1).describe("The OAuth app ID returned by tailscale_create_oauth_app")
+    }),
+    handler: async (input) => {
+      return apiGet(`/tailnet/${getTailnet()}/oauth-apps/${encPath(input.appId)}`);
+    }
   }
 ];
 
@@ -32753,6 +32811,39 @@ var localCliTools = [
     },
     inputSchema: external_exports.object({}),
     handler: async () => runTailscaleCli(["version"])
+  },
+  // The two tools below need a tailscale client >= 1.102.1 (both subcommands
+  // landed in that release). On an older binary the CLI exits non-zero with
+  // "unknown subcommand", which runTailscaleCli surfaces verbatim as the error
+  // -- an accurate, self-explaining failure, so there is no version pre-check
+  // here. Deliberately NOT passing --json: neither subcommand's flag support is
+  // verified across versions, and an unsupported flag would turn a working text
+  // response into a hard failure. Text output is the safe contract.
+  {
+    name: "tailscale_local_whoami",
+    description: "Show which Tailscale user and device this machine is currently authenticated as. Useful for confirming an agent host is enrolled under the identity you expect before trusting its access. Requires tailscale >= 1.102.1; returns the CLI's text output verbatim.",
+    annotations: {
+      title: "Tailscale whoami",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({}),
+    handler: async () => runTailscaleCli(["whoami"])
+  },
+  {
+    name: "tailscale_local_service_list",
+    description: "List the Tailscale Services visible to THIS node. Complements the admin-side service tools (tailscale_list_services etc.), which report what the tailnet has configured -- this reports what this machine can actually see and reach, which is the difference that matters when debugging a service that 'exists' but is unreachable. Requires tailscale >= 1.102.1; returns the CLI's text output verbatim.",
+    annotations: {
+      title: "Tailscale service list (local)",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({}),
+    handler: async () => runTailscaleCli(["service", "list"])
   }
 ];
 
@@ -32964,6 +33055,30 @@ var logStreamingTools = [
 ];
 
 // src/tools/posture.ts
+var STATIC_POSTURE_PROVIDERS = [
+  "falcon",
+  "fleet",
+  "huntress",
+  "intune",
+  "jamfpro",
+  "kandji",
+  "kolide",
+  "sentinelone"
+];
+function getAllowedPostureProviders() {
+  const raw = process.env.TAILSCALE_EXTRA_POSTURE_PROVIDERS;
+  if (!raw) return new Set(STATIC_POSTURE_PROVIDERS);
+  const extras = raw.split(",").map((s) => s.trim()).filter(Boolean);
+  return /* @__PURE__ */ new Set([...STATIC_POSTURE_PROVIDERS, ...extras]);
+}
+var postureProviderSchema = external_exports.string().superRefine((value, ctx) => {
+  const allowed = getAllowedPostureProviders();
+  if (allowed.has(value)) return;
+  ctx.addIssue({
+    code: "custom",
+    message: `Unknown posture provider ${JSON.stringify(value)}. Known providers: ${[...allowed].sort().join(", ")}. To allow a provider Tailscale has shipped before this package updates, set TAILSCALE_EXTRA_POSTURE_PROVIDERS=providerA,providerB in your MCP config.`
+  });
+}).meta({ enum: [...getAllowedPostureProviders()].sort() });
 var postureTools = [
   {
     name: "tailscale_list_posture_integrations",
@@ -33008,9 +33123,11 @@ var postureTools = [
       openWorldHint: true
     },
     inputSchema: external_exports.object({
-      provider: external_exports.enum(["falcon", "intune", "jamfpro", "kandji", "kolide", "sentinelone"]).describe("The posture provider"),
+      provider: postureProviderSchema.describe(
+        "The posture provider slug: falcon (CrowdStrike Falcon), fleet, huntress, intune (Microsoft Intune), jamfpro (Jamf Pro), kandji (Iru, formerly Kandji), kolide (1Password XAM, formerly Kolide), sentinelone"
+      ),
       clientId: external_exports.string().optional().describe(
-        "Client ID for the provider (Intune: application UUID; Falcon/Jamf Pro: client id; Kandji/Kolide/Sentinel One: leave blank)"
+        "Client ID for the provider (Intune: application UUID; Falcon/Jamf Pro: client id; Fleet/Huntress/Kandji/Kolide/Sentinel One: leave blank)"
       ),
       clientSecret: external_exports.string().describe(
         "The secret (auth key, token, etc.) used to authenticate with the provider. SENSITIVE: passed straight to Tailscale and not echoed back, but MCP clients may log the input value you supply."
@@ -33403,6 +33520,99 @@ var tailnetTools = [
   }
 ];
 
+// src/tools/tailnets.ts
+var organizationSchema = external_exports.string().trim().min(1).optional().describe("Organization ID. Defaults to '-' (the organization owning the calling credentials).");
+var tailnetsTools = [
+  {
+    name: "tailscale_list_org_tailnets",
+    description: "List the tailnets in your organization, including API-only tailnets created via the API. Paginated: returns at most `limit` results (Tailscale defaults to 100) plus a `cursor`. Pass that cursor back to fetch the next page; an empty cursor in the response means you have reached the end. Requires OAuth authentication.",
+    annotations: {
+      title: "List organization tailnets",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      organization: organizationSchema,
+      // No client-side ceiling: Tailscale's documented maximum for `limit` is
+      // unknown, so an invented cap would either reject values the API accepts
+      // or wave through ones it does not. Let the API be the authority and
+      // surface its 400 verbatim.
+      limit: external_exports.number().int().positive().optional().describe("Max tailnets to return in this page. Omit to use Tailscale's default of 100."),
+      cursor: external_exports.string().optional().describe("Pagination cursor from a previous response. Omit for the first page.")
+    }),
+    handler: async (input) => {
+      const params = new URLSearchParams();
+      if (input.limit !== void 0) params.set("limit", String(input.limit));
+      if (input.cursor !== void 0) params.set("cursor", input.cursor);
+      const qs = params.toString();
+      const org = encPath(input.organization ?? "-");
+      return apiGet(`/organizations/${org}/tailnets${qs ? `?${qs}` : ""}`);
+    }
+  },
+  {
+    name: "tailscale_create_org_tailnet",
+    description: "Create a new API-only tailnet in your organization. Returns the tailnet (id, displayName, orgId, dnsName, createdAt) AND a freshly-minted OAuth client for it.\n\nSECURITY: the response body contains that OAuth client's secret verbatim, and it cannot be retrieved again. MCP clients commonly persist tool responses to logs and conversation transcripts; treat this response as sensitive.\n\nRequires an OAuth client with the 'tailnets' scope -- an API key will not work. To then operate on the new tailnet, set TAILSCALE_OAUTH_TAILNET to its id and use an OAuth client with the 'all' scope.",
+    annotations: {
+      title: "Create organization tailnet",
+      readOnlyHint: false,
+      destructiveHint: false,
+      // Each call creates a distinct tailnet; there is no idempotency key.
+      idempotentHint: false,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      displayName: external_exports.string().trim().min(1).describe("Human-readable name for the new tailnet"),
+      organization: organizationSchema
+    }),
+    handler: async (input) => {
+      const org = encPath(input.organization ?? "-");
+      return apiPost(`/organizations/${org}/tailnets`, { displayName: input.displayName });
+    }
+  },
+  {
+    name: "tailscale_delete_tailnet",
+    description: "Permanently delete a tailnet. This is IRREVERSIBLE and removes every device, user, ACL, and key in it.\n\nBy default it acts on the tailnet the current credentials point at (TAILSCALE_TAILNET, or TAILSCALE_OAUTH_TAILNET when targeting an API-only tailnet). Pass `tailnet` to name a different one -- e.g. an id returned by tailscale_list_org_tailnets -- which requires credentials scoped to reach it; UNVERIFIED against a live tailnet, so expect a 403/404 if your token cannot. You must always pass `confirmTailnet` matching the effective target exactly; the call is refused locally otherwise. Intended for tearing down API-only tailnets created by tailscale_create_org_tailnet.",
+    annotations: {
+      title: "Delete tailnet",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      tailnet: external_exports.string().trim().min(1).optional().describe(
+        "Tailnet to delete (e.g. an id from tailscale_list_org_tailnets). Omit to target the configured tailnet. Requires credentials scoped to reach it."
+      ),
+      confirmTailnet: external_exports.string().trim().min(1).describe(
+        "Must exactly match the effective target -- `tailnet` when given, otherwise the configured tailnet (TAILSCALE_TAILNET / TAILSCALE_OAUTH_TAILNET). A deliberate second look before an irreversible org-wide delete."
+      )
+    }),
+    // `.trim().min(1)` on both fields, not just `.min(1)`: a bare min(1) accepts
+    // " ", which then trims to "" in the handler, goes falsy, and silently falls
+    // back to the CONFIGURED tailnet. The confirm guard still held, so it was
+    // never a wrong-target delete -- but "delete the tailnet I named" quietly
+    // becoming "delete the default one" is the wrong shape for an irreversible
+    // operation. Trimming at the schema turns it into a validation error.
+    handler: async (input) => {
+      const configured = process.env.TAILSCALE_OAUTH_TAILNET?.trim() || getTailnet();
+      const target = input.tailnet?.trim() || configured;
+      if (target === "-") {
+        throw new Error(
+          "Refusing to delete: the tailnet resolves to '-' (the default self-reference), so there is nothing specific to confirm against. Set TAILSCALE_TAILNET (or TAILSCALE_OAUTH_TAILNET) to the tailnet's explicit name or id first."
+        );
+      }
+      if (input.confirmTailnet !== target) {
+        throw new Error(
+          `confirmTailnet ${JSON.stringify(input.confirmTailnet)} does not match the configured tailnet ${JSON.stringify(target)}. Refusing to delete.`
+        );
+      }
+      return apiDelete(`/tailnet/${encPath(target)}`);
+    }
+  }
+];
+
 // src/tools/users.ts
 var userTools = [
   {
@@ -33560,7 +33770,7 @@ function getAllowedWebhookEvents() {
   return /* @__PURE__ */ new Set([...STATIC_WEBHOOK_EVENT_TYPES, ...extras]);
 }
 var endpointUrlSchema = external_exports.url().refine((u) => u.startsWith("https://"), "endpointUrl must use https://");
-var webhookSubscriptionsSchema = external_exports.array(external_exports.string()).min(1).superRefine((arr, ctx) => {
+var webhookSubscriptionsSchema = external_exports.array(external_exports.string().meta({ enum: [...getAllowedWebhookEvents()].sort() })).min(1).superRefine((arr, ctx) => {
   const allowed = getAllowedWebhookEvents();
   let knownEventsList = null;
   for (let i = 0; i < arr.length; i++) {
@@ -33726,6 +33936,12 @@ function buildToolGroups(env) {
     keys: keyTools,
     users: userTools,
     tailnet: tailnetTools,
+    // Named "org-tailnets", NOT "tailnets": a group called "tailnets" sits one
+    // character from the existing "tailnet" group (settings/contacts), and
+    // TAILSCALE_TOOLS matches names exactly with no near-miss warning. An
+    // operator who typo'd one would silently be handed the other -- and this
+    // group contains an irreversible whole-tailnet delete.
+    "org-tailnets": tailnetsTools,
     webhooks: webhookTools,
     posture: postureTools,
     audit: auditTools,
@@ -33738,6 +33954,13 @@ function buildToolGroups(env) {
   }
   return toolGroups;
 }
+function formatTailnetMismatchWarning(env) {
+  const oauthTailnet = env.TAILSCALE_OAUTH_TAILNET?.trim();
+  if (!oauthTailnet) return null;
+  const explicit = env.TAILSCALE_TAILNET?.trim();
+  if (!explicit || explicit === "-" || explicit === oauthTailnet) return null;
+  return `TAILSCALE_OAUTH_TAILNET="${oauthTailnet}" but TAILSCALE_TAILNET="${explicit}". The OAuth token will be scoped to the former while tool requests are addressed to the latter, so every tailnet-scoped tool will fail with HTTP 403. Either unset TAILSCALE_TAILNET (or set it to "-") to follow the token, or set both to the same tailnet.`;
+}
 function formatBannerFilterSuffix(inputs) {
   const profileValid = !!inputs.profileEnv && !inputs.unknownProfile;
   const profileLabel = profileValid ? inputs.explicitTools && inputs.profileWouldFilter ? `profile=${inputs.profileEnv} (overridden by TAILSCALE_TOOLS)` : `profile=${inputs.profileEnv}` : null;
@@ -33824,7 +34047,7 @@ async function tailnetDnsResource(uri) {
 }
 
 // src/index.ts
-var version2 = true ? "0.15.0" : resolveVersionFallback();
+var version2 = true ? "0.17.0" : resolveVersionFallback();
 var subcommand = process.argv[2];
 var cliSubcommandHandled = false;
 if (subcommand === "deploy-acl" || subcommand === "validate-acl") {
@@ -33875,6 +34098,10 @@ if (!cliSubcommandHandled) {
       `@yawlabs/tailscale-mcp: internal inconsistency -- TAILSCALE_PROFILE="${process.env.TAILSCALE_PROFILE}" references group(s) that are not registered: ${unknownProfileGroups.join(", ")}. Those groups contributed no tools. This is a bug in @yawlabs/tailscale-mcp, not your configuration -- please report it at https://github.com/YawLabs/tailscale-mcp/issues.`
     );
   }
+  const tailnetMismatch = formatTailnetMismatchWarning(process.env);
+  if (tailnetMismatch) {
+    console.error(`@yawlabs/tailscale-mcp: ${tailnetMismatch}`);
+  }
   if (unknownProfile) {
     console.error(
       `@yawlabs/tailscale-mcp: TAILSCALE_PROFILE="${unknownProfile}" is not a known profile. Valid profiles: minimal, core, full. Falling back to no profile filter.`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/tailscale-mcp",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "mcpName": "io.github.YawLabs/tailscale-mcp",
   "description": "Tailscale MCP server for managing your tailnet from AI assistants",
   "license": "MIT",