NetBird's MCP server lets coding agents change the network, read-only unless you opt in

Claude Code, Codex, Cursor, and VS Code can now manage a NetBird account over MCP. The consent default is the part that matters: OAuth always includes read access, and Make changes is unticked until the user opts in. A personal access token has no read-only choice. It carries that user's full rights, so a role that can create users, mint setup keys, or rewrite policies and DNS can do those things through the agent with no extra opt-in.

On 14 November 2026, NetBird's @netbird account said those clients can manage peers, groups, policies, networks, and DNS with the signed-in user's permissions, using OAuth that is read-only by default. The management docs, updated 12 November 2026, describe the same server. Each MCP tool maps to one operation of the NetBird REST API, runs the same handler and permission checks, and returns the same JSON. The agent can do only what that role already allows.

The new connection is read-only until you tick the box

Add the server without a token and the client opens a NetBird page asking whether to allow the application to access NetBird. The page names the application and the host the sign-in returns to. Read your NetBird configuration is always included. Make changes — create, update, and delete — starts unticked, so the connection is read-only. If the client asks only for read-only access, that option is not shown. NetBird asks for consent on every sign-in.

Read-only does not hide the write tools. The agent still sees them. Calling one returns an error that the connection was authorized to read only. Allowing changes means signing in again and ticking Make changes.

A personal access token skips that split. A service user's token reads everything in the account whatever its role, and changes only what its role allows. Service users act only through personal access tokens; OAuth does not work for them. Users with the User, Agent Network Admin, or Usage Viewer role cannot create those tokens, so they connect with OAuth.

Four limits stack. The user's role still applies: an Auditor can use every read-only tool and none that change data, and a User can see little more than their own peers. A self-hosted administrator can withhold tools outside an allow-list. Tools act only on the account signed in to, or the MSP tenant in the URL. No tool takes an account ID, so a call cannot be aimed at another account.

Write access can mint keys and reset fields you omit

With changes allowed, tools can list and change peers, groups, access policies, posture checks, networks, routes, and DNS, and can create, update, and delete users and setup keys. They can read the audit log. They cannot delete the account, manage personal access tokens or invite links, change identity-provider settings, or call Agent Network. The docs keep that last item separate: Agent Network routes agents' LLM traffic through NetBird; this server lets an agent change NetBird configuration.

Secrets the API returns once are returned to the agent the same way. create_setup_key hands the key over once. create_user can hand over the initial password of a user created in the embedded identity provider. List and get tools for setup keys never return the key. Peer IPs, user emails, new setup keys, and those passwords also go to the model provider the client uses.

update_ tools replace the whole object. A field left out is reset. update_group without peers removes every peer from the group. update_account without ipv6_enabled_groups turns IPv6 off for all peers. Descriptions tell the agent to fetch the object first and send every field back, and the server rejects unknown or mistyped fields. That is not a substitute for reading the payload before you approve it.

Annotations do not cover every write. All update_ and delete_ tools, and reject_user, are marked destructive. create_ tools and approve_user are marked as neither, so a client that prompts only before destructive tools runs them without asking. Keep approval prompts on for NetBird tools that change data, and do not use a mode that approves tool calls automatically on a connection that can make changes.

The audit log will not flag the agent. Changes appear as ordinary actions of the signed-in user. Nothing marks them as made through MCP. OAuth sessions do add their own entries — signed in, signed out, or revoked after token reuse — with the granted access (read or read and write), a client name the application chooses, and, on sign-in, the redirect host. That name does not prove which application signed in. A personal access token records no MCP entry. Neither does a cancelled sign-in, or a session that simply reaches its 30-day end.

Cloud is reachable. Self-hosted stays dark until an admin enables it.

Cloud clients connect to https://api.netbird.io/api/mcp over the MCP streamable HTTP transport. On self-hosted NetBird the server is off until an administrator turns it on. The 14 November post names that switch NB_MCP_ENABLED=true. Until then, management serves no MCP or OAuth path, and those requests get a 404.

NetBird Cloud has no account setting that turns the server off or limits its tools. Every user of an account can connect a client, whatever their role, and then acts with that role. OAuth access tokens last one hour and refresh without a prompt. The session lasts 30 days from sign-in; refresh does not extend it. Sign out in a client that revokes tokens to cut one OAuth connection, or delete the token to cut a personal access token. Block or remove the user to stop every MCP connection of that user on the next call. Disabling the user only in the identity provider does not end sessions already open; that waits until the next sign-in, at most 30 days later. Block the user in NetBird to cut access right away.

Names and audit text the tools return can be data someone else controls, and that text can try to steer the agent.

Before you add a client, read the MCP server docs, leave Make changes unticked, and keep approval prompts on if you later grant write access. On self-hosted NetBird, leave the server disabled until you have decided who should be able to call it.

Sources

• NetBird on X, 14 November 2026 x.com
• NetBird MCP Server documentation docs.netbird.io