Skip to main content

Public MCP Server

The public MCP server is the endpoint noBGP hosts for you:

https://mcp.nobgp.com/mcp

It speaks for your account — every network and organization you belong to. Point an AI client at it and it can list your fleet, create networks, provision and register nodes, publish services, run commands, move files, and watch events, on machines behind NAT, CGNAT and firewalls that ssh, scp and curl cannot reach.

This page is the guide — what the endpoint is, how to connect to it, and how it authenticates. For the tools themselves, see the MCP Reference, which covers this surface and the local server side by side.

Connect a client​

  • Claude Desktop — add noBGP as a custom connector
  • Claude Code — an http server entry in .mcp.json
  • ChatGPT — the pre-configured Custom GPT, or noBGP as a Developer Mode connector

What only this surface can do​

A node's local server exposes a deliberate subset of the same tools. The things it deliberately cannot do all live here:

  • Create and destroy — network_create, network_delete, provision_node, deprovision_node, register_node
  • Organizations and billing — org_create, org_update, org_sso_setup, org_sso_set_enforced
  • Publish services — service_publish, service_update, service_delete, service_share
  • Widen a node's reach — node_label, node_grant, node_revoke
  • See across networks — network_directory, and any call naming a network other than one node's own

A granted node is bounded to its own network and cannot grant or label, so it can never widen its own reach. That boundary is the reason both surfaces exist.

Authentication​

All endpoints require a Bearer token.

  • MCP (https://mcp.nobgp.com/mcp): OAuth 2.0 Authorization Code Flow with PKCE. Sign in with any provider offered on the noBGP login page (Google, GitHub, and any SSO connection your organization has configured). Token refresh is automatic; session management is per-conversation.
  • REST / OpenAPI: supply the same Bearer token via the Authorization header.

Scopes​

Each tool advertises the scope family it belongs to via x-nobgp-auth-scopes in the OpenAPI schema and GET /api/v1/tools. Scopes are advisory classification for clients; authorization is enforced by organization role (see the role notes on each tool). A denied call returns forbidden (HTTP 403).

ScopeTools
(none)whoami, node_label, node_grant, node_revoke, command_subscribe, the event tools (fs_subscribe, presence_subscribe, event_tail, event_unsubscribe, event_publish, event_subscriptions), and the SSO/billing tools
network.readnetwork_directory
network.writenetwork_create, network_delete
org.writeorg_create
node.registerregister_node
provisioning.writeprovision_node, deprovision_node
service.writeservice_publish, service_update, service_delete, service_share
shell.execcommand
fs.readfile (read/list/stat), fs_read, fs_list, fs_stat, fs_glob, fs_grep, fs_grep_subscribe
fs.writefile (write/edit/delete/mkdir), fs_write, fs_edit, fs_delete, fs_mkdir
net.readnet_peers, net_interfaces, net_metrics, net_routes, net_dns
members.manageorg_update

Transport adapters​

The same canonical tools registry is reachable over three adapters. Parameters and response shapes are identical — only framing, auth carrier, and streaming delivery differ.

MCP — /mcp​

JSON-RPC 2.0 over Streamable HTTP. Tools advertised via tools/list; invoked via tools/call. Streaming tools deliver chunks as notifications/progress messages; one-shot tools return their full response in the tools/call result.

REST — POST /api/v1/tools/{name}​

Request struct as JSON body. Success envelope:

{ "data": { "...typed response..." }, "message": "human-readable summary" }

Error envelope:

{ "error": { "code": "not_found", "message": "..." } }

Streaming tools (fs_grep) negotiate via Accept: text/event-stream and respond with SSE events: chunk, progress, done, error.

OpenAPI — GET /api/v1/openapi.json​

OpenAPI 3.1 spec served live from any router replica. Use it as a build input for SDK generation. Every tool appears under /api/v1/tools/{name} with full request/response schemas.

Tool index — GET /api/v1/tools​

Returns a brief index (name, description, mode, capabilities) for quick introspection.

Execution modes​

  • one_shot — request in, response out. Used by every read tool and most write tools.
  • server_stream — long-running tool that emits incremental progress events (SSE on REST, MCP progress on MCP). Currently only fs_grep.

Whether fs_grep matches actually arrive incrementally depends on the node: a search that has to run as the node's configured user — the usual case, since registration sets user to the installing account — is performed by the agent's privilege-dropped file worker, which answers with one reply per request. The response shape and the SSE framing are the same either way; the matches simply land when the walk finishes instead of as they are found. On agent 0.4.34 that case was refused outright; upgrade to 0.4.35 if fs_grep fails on a node.

A few tools (command, file read/write) are technically one_shot but expose a session-based workflow: the first call returns a session id, subsequent calls pass that id to continue. See Cross-replica session forwarding.

REST-only tools

fs_glob (doublestar pattern match) is available via the versioned REST surface at POST /api/v1/tools/fs_glob and is not registered over MCP. It is a one-shot call; nothing about the transport prevents it, so this may change.

fs_grep is on MCP — see fs_grep for how its results arrive, which depends on whether you send a progressToken.

org_update is likewise REST-only — it is intended for dashboard/management clients rather than the conversational MCP toolset. So are the remaining organization-membership, audit, and billing operations (org_members_list, org_invite_*, org_member_*, org_leave, org_transfer_ownership, org_audit_list, create_checkout, create_billing_portal, set_spend_cap); their behavior is described on the Organizations and Plans & Billing pages.

Rate limiting​

Requests may return rate_limited with a Retry-After hint — back off and retry.

A rate_limited error includes details.retry_after_ms. Streaming tools (fs_grep) also count against a global in-flight slot pool (default 8 concurrent streams) — exhaustion surfaces as resource_exhausted (HTTP 429) rather than rate_limited. The pool frees up as in-flight streams finish, so this case is safe to retry shortly.

Audit logging​

The router emits one structured audit event per tool invocation, capturing who called the tool, which tool ran, the target it acted on, when it ran, and the outcome. Tool arguments are not captured — they can contain secrets (tokens, keys, sensitive paths), so only that narrow summary is logged. Events are written to the per-organization audit log.

Versioning​

The router and the agent are versioned independently. Tool schemas are forward-compatible: response struct field additions land without a major bump and are absorbed by the loose-output-schema in the MCP adapter, so cached clients don't break on new fields.

Field renames or type changes are breaking and require a coordinated agent + router release. CI diffs a committed OpenAPI snapshot on every change to catch unintended drift.

For the authoritative machine-readable schemas, fetch /api/v1/openapi.json live from any router replica.

Next Steps​

Additional Resources​