Tailscale MCP server
93 operations0 webhooks
Run a tailnet from an agent: list and approve devices, mint tagged, ephemeral auth keys for new nodes, read, validate and safely update the policy file (ACLs and grants, with etag checks and ACL tests), publish internal apps and MCP servers as Tailscale Services, and manage DNS, users, invites, webhooks, posture attributes and the configuration audit log (93 operations).
Try Tailscale with your agent
Connect Tailscale, then paste this into Claude, ChatGPT or Cursor. For ideas from other apps, see the use cases.
Using Corsair, show me what you can do in Tailscale on my account, then run one read-only example and show me the result.
Tailscale tools and triggers
Tools are what your agent can do in Tailscale through Corsair's MCP server. Triggers are the Tailscale events a routine can start from.
Devices
- AuthorizeWrite
Approve (authorized: true) or revoke approval for (authorized: false) a device when the tailnet requires device approval. Revoking cuts the device's access until it is approved again. deviceId is the device `id` or `nodeId` from devices.list.
devices.authorize
- DeleteDestructive
Remove a device from the tailnet. It loses access at once and must be signed in again (with a new auth key or login) to rejoin. Cannot be undone. deviceId is the device `id` or `nodeId` from devices.list.
devices.delete
- Expire KeyDestructive
Expire a device's node key now: the device is disconnected until someone signs in on it again. Use it to cut off a lost or compromised machine. deviceId is the device `id` or `nodeId` from devices.list.
devices.expireKey
- GetRead-only
Get one device. fields: "all" adds routes, posture and connectivity details. deviceId is the device `id` or `nodeId` from devices.list.
devices.get
- ListRead-only
List the devices in the tailnet: name, hostname, Tailscale IPs, owner, OS, client version, tags, last seen, key expiry, authorized. Pass fields: "all" to add advertised and enabled routes, posture and connectivity details. filters narrows the list on the server by exact match on top-level device fields, all of them required to match (for example { tags: ["tag:prod"], isEphemeral: true }).
devices.list
- Posture Attributes.Batch UpdateWrite
Set or delete custom posture attributes on many devices in one call. A null value deletes that attribute. Applied all together or not at all.
devices.postureAttributes.batchUpdate
- Posture Attributes.DeleteWrite
Delete a custom posture attribute (custom:...) from a device. deviceId is the device `id` or `nodeId` from devices.list.
devices.postureAttributes.delete
- Posture Attributes.GetRead-only
Get a device's posture attributes: Tailscale's own (node:os, node:tsVersion, node:tsReleaseTrack, ...) and custom ones (custom:<name>) set through the API or a posture integration. deviceId is the device `id` or `nodeId` from devices.list.
devices.postureAttributes.get
- Posture Attributes.SetWrite
Set a custom posture attribute on a device. attributeKey must start with custom: (for example custom:agentApproved); value is a string, number or boolean. expiry (RFC 3339) makes it lapse on its own. Policy postures can then allow or deny access on it. deviceId is the device `id` or `nodeId` from devices.list.
devices.postureAttributes.set
- Routes.ListRead-only
List the subnet routes and exit-node routes a device advertises and which of them are enabled. deviceId is the device `id` or `nodeId` from devices.list.
devices.routes.list
- Routes.SetWrite
Set which of the routes a device advertises are enabled (subnet routes, and 0.0.0.0/0 plus ::/0 for an exit node). Replaces the enabled list: routes left out are turned off. Only routes the device advertises can be enabled. deviceId is the device `id` or `nodeId` from devices.list.
devices.routes.set
- Set IpWrite
Change a device's Tailscale IPv4 address to an unused one in the tailnet's range (100.64.0.0/10 by default). Existing connections to the old address break and must reconnect to the new one. deviceId is the device `id` or `nodeId` from devices.list.
devices.setIp
- Set NameWrite
Rename a device: its MagicDNS name becomes <name>.<tailnet>.ts.net. Pass name: "" to go back to the machine's own hostname. Connections using the old name stop resolving. deviceId is the device `id` or `nodeId` from devices.list.
devices.setName
- Set TagsWrite
Replace a device's ACL tags (tag:server, tag:mcp, ...). Each tag must be defined in the policy file and owned by the caller (tagOwners). Tagging a user's device turns it into a tagged device that no longer belongs to that user, and the access rules for its tags apply from then on. Pass tags: [] to remove every tag. deviceId is the device `id` or `nodeId` from devices.list.
devices.setTags
- Update KeyWrite
Turn key expiry off (keyExpiryDisabled: true) or back on for a device, for servers that should stay signed in. deviceId is the device `id` or `nodeId` from devices.list.
devices.updateKey
Dns
- Configuration.GetRead-only
Get the tailnet's whole DNS configuration in one object: nameservers, split DNS, search paths and preferences.
dns.configuration.get
- Configuration.SetWrite
Replace the tailnet's whole DNS configuration in one call (nameservers, split DNS, search paths, preferences).
dns.configuration.set
- Nameservers.ListRead-only
List the global DNS nameservers devices use.
dns.nameservers.list
- Nameservers.SetWrite
Replace the global DNS nameservers (IP addresses). An empty list removes them all and turns MagicDNS off.
dns.nameservers.set
- Preferences.GetRead-only
Get whether MagicDNS is on.
dns.preferences.get
- Preferences.SetWrite
Turn MagicDNS on or off. Turning it on needs at least one nameserver; turning it off breaks <name>.ts.net lookups.
dns.preferences.set
- Search Paths.ListRead-only
List the DNS search domains pushed to devices.
dns.searchPaths.list
- Search Paths.SetWrite
Replace the DNS search domains pushed to devices.
dns.searchPaths.set
- Split Dns.GetRead-only
Get split DNS: which nameservers answer for which domains.
dns.splitDns.get
- Split Dns.SetWrite
Replace the whole split DNS map (domain to nameservers). Domains left out are removed.
dns.splitDns.set
- Split Dns.UpdateWrite
Change split DNS for the given domains only; a domain set to null is removed, others are kept.
dns.splitDns.update
Logging
- Aws External Id.GetWrite
Get (or create on first use) the AWS external ID to put in an IAM role trust policy before streaming logs to S3.
logging.awsExternalId.get
- Aws External Id.ValidateRead-only
Check that an IAM role trusts Tailscale with this external ID, before log streaming to S3 is turned on.
logging.awsExternalId.validate
- Configuration Logs.ListRead-only
Read the configuration audit log between start and end (RFC 3339): who changed the policy file, approved or deleted a device, created a key, changed a setting, with old and new values. Filter by actor, target or event (TAILNET.UPDATE.ACL, NODE.CREATE, NODE.APPROVE, API_KEY.CREATE, USER.UPDATE.USER_ROLE, ...). Use it to answer "who changed what, and when".
logging.configurationLogs.list
- Network Logs.ListRead-only
Read network flow logs between start and end (RFC 3339): which device talked to which, over what protocol and ports, and how many bytes. Network flow logging must be turned on (Premium and Enterprise plans).
logging.networkLogs.list
- Streaming.DisableDestructive
Stop streaming configuration or network logs; the destination settings are removed.
logging.streaming.disable
- Streaming.GetRead-only
Get where configuration or network logs are streamed (Splunk, Elastic, Panther, Cribl, CrowdStrike, Datadog, Axiom or S3).
logging.streaming.get
- Streaming.Get StatusRead-only
Get whether log streaming to a SIEM is working for configuration or network logs, and its last errors.
logging.streaming.getStatus
- Streaming.SetWrite
Start or change streaming of configuration or network logs to a SIEM or bucket. Replaces the current destination.
logging.streaming.set
Services
- DeleteDestructive
Delete a Tailscale Service; its address stops answering on every host.
services.delete
- GetRead-only
Get a Tailscale Service: its addresses, ports, tags and comment. serviceName is svc:<name>.
services.get
- Hosts.Get ApprovalRead-only
Get whether a device is approved to serve a Tailscale Service.
services.hosts.getApproval
- Hosts.ListRead-only
List the devices that advertise a Tailscale Service and whether each is approved to serve it.
services.hosts.list
- Hosts.Set ApprovalWrite
Approve (approved: true) or stop (false) a device serving a Tailscale Service, when its tags are not auto-approved.
services.hosts.setApproval
- ListRead-only
List Tailscale Services: named virtual endpoints (svc:<name>) with their own Tailscale IPs and MagicDNS name, served by one or more hosts. Use them to give an internal app or MCP server a stable address on the tailnet.
services.list
- UpdateWrite
Create or replace a Tailscale Service (serviceName svc:<name>; name defaults to it): ports ("tcp:443", "do-not-validate") and tags. Hosts then advertise it with `tailscale serve --service=svc:<name>`, and the policy file grants who may reach it.
services.update
Users
- ApproveWrite
Approve a user waiting for approval (when the tailnet requires user approval).
users.approve
- DeleteDestructive
Delete a user from the tailnet, with their devices. Cannot be undone; users.suspend keeps them restorable. A user's own token can't delete that user.
users.delete
- GetRead-only
Get one user: role, status, login name, device count, last seen.
users.get
- ListRead-only
List users: role, status (active, idle, suspended, needs-approval), device count, last seen. type and role filter the list.
users.list
- RestoreWrite
Restore a suspended user and their access.
users.restore
- SuspendWrite
Suspend a user: they lose access to the tailnet until restored; their devices and settings are kept. A user's own token can't suspend that user.
users.suspend
- Update RoleWrite
Change a user's role (member, admin, it-admin, network-admin, billing-admin, auditor, owner).
users.updateRole
Webhooks
- CreateWrite
Add a webhook endpoint for tailnet events (nodeCreated, nodeNeedsApproval, nodeKeyExpiringInOneDay, nodeDeleted, policyUpdate, userNeedsApproval, userRoleUpdated, ...), or a whole category (categoryTailnetManagement, categoryDeviceMisconfigurations) that also takes events Tailscale adds later. Tailscale signs each event with the secret (Tailscale-Webhook-Signature). providerType "slack", "discord", "mattermost" or "googlechat" formats the message for that chat app; "" or none sends the generic format. The signing secret is returned once: keep it to verify events.
webhooks.create
- DeleteDestructive
Delete a webhook endpoint; Tailscale stops sending it events.
webhooks.delete
- GetRead-only
Get a webhook endpoint: URL, provider type and subscribed events.
webhooks.get
- ListRead-only
List the webhook endpoints that receive tailnet events (device added, needs approval, policy changed, user joined, ...).
webhooks.list
- Rotate SecretDestructive
Replace a webhook endpoint's signing secret. The new one is returned once; signatures made with the old one stop verifying.
webhooks.rotateSecret
- TestDestructive
Send a test event to a webhook endpoint (a chat channel, for a Slack or Discord one) to check it receives and accepts deliveries.
webhooks.test
- UpdateWrite
Change which events a webhook endpoint receives.
webhooks.update
Device Invites
- AcceptWrite
Accept a device share invite from another tailnet into this key's tailnet, by its invite URL or code. The shared device then appears in devices.list. Needs a user's API access token: a share belongs to a user, so an OAuth client can't accept one.
deviceInvites.accept
- CreateDestructive
Share a device with people outside the tailnet. Each invite gives an invite URL to send; with email set, Tailscale emails the invite itself. allowExitNode lets the recipient use the device as an exit node; multiUse lets several people accept one link. deviceId is the device `id` or `nodeId` from devices.list.
deviceInvites.create
- DeleteWrite
Delete a device share invite; its link stops working.
deviceInvites.delete
- GetRead-only
Get a device share invite: its invite URL, who accepted it and when.
deviceInvites.get
- ListRead-only
List the share invites for a device (who it was shared with, accepted or not); null when there are none. deviceId is the device `id` or `nodeId` from devices.list.
deviceInvites.list
- ResendDestructive
Email a device share invite again to the address it was created for.
deviceInvites.resend
Keys
- CreateDestructive
Create an auth key (keyType "auth", the default) that adds a device to the tailnet, or a trust credential (keyType "client" for an OAuth client, "federated" for a federated identity). For an agent or server, make the auth key preauthorized, tagged (capabilities.devices.create.tags) and ephemeral so the node is removed when it goes offline. The secret is returned once in `key`: hand it to the machine right away, never paste it into chat.
keys.create
- DeleteDestructive
Revoke a key. Devices already added with an auth key stay; anything using a revoked API token or OAuth client stops working. Cannot be undone.
keys.delete
- GetRead-only
Get a key: type, description, scopes, tags, created, expires, revoked. Never returns the secret.
keys.get
- ListRead-only
List the keys of the caller (all: true for every key in the tailnet): auth keys, API access tokens, OAuth clients and federated identities, with expiry, scopes and tags. Never returns the secrets.
keys.list
- UpdateWrite
Change an OAuth client's or federated identity's description, scopes or tags (auth keys and API tokens can't be edited).
keys.update
Oauth Apps
- CreateDestructive
Register an OAuth app in the tailnet with its redirect URIs and scopes. The client secret is returned once.
oauthApps.create
- DeleteDestructive
Delete an OAuth app; sign-ins and tokens issued through it stop working.
oauthApps.delete
- GetRead-only
Get an OAuth app: name, redirect URIs, scopes. Never returns the secret.
oauthApps.get
- ListRead-only
List the OAuth apps registered in the tailnet (apps people in the tailnet sign in to so it can act on their behalf).
oauthApps.list
- UpdateWrite
Replace an OAuth app's name, redirect URIs or scopes.
oauthApps.update
Posture Integrations
- CreateWrite
Connect a device posture provider, so its attributes (compliance, risk score) can gate access in the policy file.
postureIntegrations.create
- DeleteDestructive
Disconnect a device posture provider; rules that rely on its attributes stop matching.
postureIntegrations.delete
- GetRead-only
Get a device posture integration and its sync status.
postureIntegrations.get
- ListRead-only
List device posture integrations (CrowdStrike Falcon, Intune, Jamf Pro, Kandji, Kolide, SentinelOne, ...).
postureIntegrations.list
- UpdateWrite
Change a device posture integration (credentials, tenant, which devices it reads).
postureIntegrations.update
User Invites
- CreateDestructive
Invite people to join the tailnet with a role (member, admin, ...). Each invite gives an invite URL; with email set, Tailscale emails it. Needs a user's API access token (an invite needs an inviting user), not an OAuth client.
userInvites.create
- DeleteWrite
Delete an invite to join the tailnet; its link stops working. Needs a user's API access token.
userInvites.delete
- GetRead-only
Get an invite to join the tailnet: role, invite URL, email and whether it was accepted.
userInvites.get
- ListRead-only
List pending invites for people to join the tailnet; null when there are none. Invites need a user's API access token, not an OAuth client.
userInvites.list
- ResendDestructive
Email an invite to join the tailnet again.
userInvites.resend
Policy File
- GetRead-only
Get the tailnet's policy file (ACLs or grants, groups, tagOwners, autoApprovers, postures, tests). format "hujson" (the default) keeps comments and returns the text; "json" returns an object without comments. etag is the version: pass it as ifMatch to policyFile.set so another edit made in between is not overwritten. details: true also returns warnings and errors.
policyFile.get
- PreviewRead-only
Show which rules of the policy file you pass apply to a user (type "user", previewFor their email) or a destination (type "ipport", previewFor "100.101.102.103:443"), without saving anything. policy is required: pass a draft, or the text from policyFile.get to preview the current file.
policyFile.preview
- SetDestructive
Replace the tailnet's policy file, as HuJSON text (keeps comments) or a JSON object. It controls who can reach what across the whole tailnet, so run policyFile.validate first, and pass ifMatch with the etag from policyFile.get: Tailscale then refuses the write if the file changed since. Tests in the file must pass or nothing is saved.
policyFile.set
- ValidateRead-only
Check a draft policy file without saving it: pass policy (HuJSON text or object) to parse it and run its tests, or tests (at least one) to run ACL tests against the current file. null or an empty message means everything passed. Problems still answer 200: message holds the parse error, or "test(s) failed" with each failing test in data.
policyFile.validate
Contacts
- GetRead-only
Get the tailnet's account, support and security contact emails.
contacts.get
- Resend Verification EmailDestructive
Email the verification link for a contact address again.
contacts.resendVerificationEmail
- UpdateDestructive
Change the account, support or security contact email. Tailscale emails the new address to verify it.
contacts.update
Tailnets
- CreateDestructive
Create an API-only tailnet in the organization (no human users, not in the admin console), for an app or agent fleet that manages its own network. At most 10 tailnets per organization. The new OAuth client secret is returned once.
tailnets.create
- DeleteDestructive
Delete a whole tailnet with all of its users, devices and settings. Only API-only tailnets can be deleted this way. Cannot be undone.
tailnets.delete
- ListRead-only
List the tailnets in the organization: the original one and any API-only tailnets made with tailnets.create. Pages with cursor.
tailnets.list
Tailnet Settings
- GetRead-only
Get tailnet settings: device and user approval, device auto-updates, key expiry days, who may join, posture identity collection, network flow logging, regional routing, HTTPS.
tailnetSettings.get
- UpdateWrite
Change tailnet settings; only the fields sent change. Turning on device approval holds every new device until someone approves it. Tailscale answers without the new values: read them with tailnetSettings.get.
tailnetSettings.update
Connect Tailscale to Claude, ChatGPT or Cursor
- 1
Connect Tailscale in Corsair
Add your Tailscale API key once in Corsair. Corsair stores the credential encrypted and makes the Tailscale API calls for your agent, so it never goes into a prompt or a config file. Connect Tailscale
If your link lets the agent add apps, you can skip this: it gives you a sign-in link the first time it needs Tailscale. On a ChatGPT personal plan, connect Tailscale here first.
- 2
Add Corsair's MCP server to your agent
Every client uses the same address:
https://mcp.corsair.dev/mcpOpen Customize → Connectors → Add custom connector, paste the address, then select Connect.Add a custom MCP server with the address and choose OAuth. Personal plans get read tools only.Add to CursorOr add this to~/.cursor/mcp.json. Cursor opens Corsair to sign in the first time it connects.{ "mcpServers": { "corsair": { "url": "https://mcp.corsair.dev/mcp" } } }Run this, then run/mcpin Claude Code to sign in.claude mcp add --transport http corsair https://mcp.corsair.dev/mcpCodex, Gemini CLI, VS Code, Zed and other clients with OAuth sign-in work the same way. Clients without it, such as GitHub Copilot's coding agent, use a link's own address and an API key. Setup for every client
- 3
Sign in and choose what needs your approval
Your client opens Corsair to sign in. Pick a link: the apps your agent can use and a mode that decides what it may do without asking. In the default Cautious mode, Tailscale's read and write operations run right away and its 22 destructive operations wait for your approval. Strict mode asks before every write and refuses destructive operations, and Read mode allows reads only.
FAQ
Install corsair and @corsair-dev/tailscale, add the Tailscale plugin, and connect with an API key. Then call methods like corsair.tailscale.api.contacts.get() from your app. Corsair keeps each tenant isolated.
Yes. Tailscale requires an API key from your Tailscale account or developer dashboard. Create credentials with access that matches what you automate, then paste them into Corsair or connect through managed auth in Hub.
Yes. One Corsair client can hit Tailscale, GitHub, Notion, Stripe, and the rest. Trigger Tailscale from a webhook, push updates to Slack, or chain actions across plugins. Same tenant context across integrations, plain TypeScript.
Teams use Corsair for run a tailnet from an agent: list and approve devices, mint tagged, ephemeral auth keys for new nodes, read, validate and safely update the policy file (ACLs and grants, with etag checks and ACL tests), publish internal apps and MCP servers as Tailscale Services, and manage DNS, users, invites, webhooks, posture attributes and the configuration audit log (93 operations). Common builds include sync jobs, admin tooling, and agents that call Tailscale APIs from your backend.
The SDK is open source. Self-host and you pay Corsair nothing for the integration layer. Hub bills for hosted auth and execution, not per Tailscale API call. Hub has a generous free tier. For hobby projects you can probably run the whole thing on free. Paid plans start to matter with more tenants or heavier traffic.
We maintain @corsair-dev/tailscale in the open repo. When Tailscale ships API changes, upgrade the package. Your call sites stay typed. You should not need to rewrite the integration layer each time.
No. Corsair does not read your Tailscale data or hold individual access credentials. Credentials stay in your database. API calls run on your instance. We do not store Tailscale data on your behalf.
Yes. Add https://mcp.corsair.dev/mcp as a custom connector or MCP server in Claude, ChatGPT, Cursor, VS Code, Claude Code, Codex or any client that supports remote MCP servers with OAuth sign-in, then sign in to Corsair. On ChatGPT personal plans, custom servers currently get read tools only.
Yes. Put Tailscale on a link in Strict mode and every write waits for your approval, while destructive actions are refused. The default Cautious mode asks only before the 22 destructive Tailscale operations. You can change a link's mode at hub.corsair.dev/me.