Skip to main content

MCP Tools Reference

Technical reference for all Model Context Protocol (MCP) tools provided by the noBGP MCP server. This documentation is intended for developers building integrations or users wanting to understand the underlying capabilities.

MCP Endpoint​

https://preview.nobgp.com/mcp

Authentication​

All MCP tools require OAuth 2.0 authentication. The MCP server uses:

  • Authorization Code Flow with PKCE
  • Supported providers: Google, GitHub, Facebook, Discord, LinkedIn, and more
  • Token refresh: Automatic
  • Session management: Per-conversation state

Available Tools​

noBGP provides 11 MCP tools organized by function:

Network Management:

Node Management:

Service Publishing:

Command Execution:

  • command - Run commands and manage interactive shell sessions

User Management:

  • whoami - User identity and metadata

network_directory​

List networks, nodes, and published services accessible to the authenticated user.

Purpose​

Primary discovery tool - shows the current state of all infrastructure.

Input Schema​

{
  "network_name": "string (optional)"
}

Parameters:

  • network_name - Specific network name to filter results. If omitted, returns all networks.

Output Schema​

{
  "networks": [
    {
      "name": "string",
      "id": "string",
      "created": "timestamp",
      "files_url": "string",
      "nodes": [
        {
          "name": "string",
          "online": "boolean",
          "info": {
            "hostname": "string",
            "agent_version": "string",
            "platform": "string",
            "platform_version": "string",
            "kernel_arch": "string",
            "virtualization": "string"
          },
          "task_id": "string (provisioning UUID, if applicable)",
          "services": [
            {
              "id": "string",
              "title": "string",
              "url": "string",
              "public_url": "string",
              "command": "string"
            }
          ]
        }
      ]
    }
  ]
}

Example Usage​

Request:

{
  "network_name": "production"
}

Response:

{
  "networks": [
    {
      "name": "production",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "created": "2024-10-15T09:00:00Z",
      "files_url": "https://files.nobgp.com/production/",
      "nodes": [
        {
          "name": "web-server-1",
          "online": true,
          "info": {
            "hostname": "web-server-1",
            "agent_version": "0.3.1",
            "platform": "debian",
            "platform_version": "12",
            "kernel_arch": "x86_64"
          },
          "services": [
            {
              "id": "svc_xyz789",
              "title": "staging-app",
              "public_url": "https://abc123.nobgp.com"
            }
          ]
        }
      ]
    }
  ]
}

Use Cases​

  • Initial discovery when starting a conversation
  • Checking current infrastructure state
  • Finding available nodes for operations
  • Listing all published services

network_create​

Create a new isolated network.

Purpose​

Provision a new network namespace for connecting nodes.

Input Schema​

{
  "name": "string (required)"
}

Parameters:

  • name - Unique name for the network (DNS-compatible, unique per user)

Output Schema​

{
  "network_id": "string",
  "name": "string",
  "index": "number",
  "created_at": "timestamp"
}

Example Usage​

Request:

{
  "name": "staging"
}

Response:

{
  "network_id": "net_def456",
  "name": "staging",
  "index": 2,
  "created_at": "2025-11-04T14:35:00Z"
}

Use Cases​

  • Creating isolated environments (dev, staging, prod)
  • Separating different projects
  • Multi-tenancy within a single account

network_delete​

Delete an existing network.

Purpose​

Remove an empty network.

warning

Destructive operation. All nodes must be removed before the network can be deleted.

Input Schema​

{
  "network_name": "string (optional)"
}

Parameters:

  • network_name - Name of the network to delete. If omitted and only one network exists, it will be selected automatically.

Output Schema​

{
  "network_id": "string",
  "name": "string",
  "nodes_removed": "number",
  "message": "string"
}

Example Usage​

Request:

{
  "network_name": "old-testing"
}

Response:

{
  "network_id": "net_abc123",
  "name": "old-testing",
  "nodes_removed": 0,
  "message": "Deleted network \"old-testing\" (id: net_abc123)"
}

Safety Features​

  • AI assistants typically ask user for confirmation first
  • Deletion is rejected if any nodes remain — remove or deprovision all nodes first
  • Cannot delete network with active provisioned nodes (must deprovision first)

provision_node​

Provision a new compute instance on a cloud provider.

Access Required

Requires provisioning permissions. Contact support if you don't have access.

Purpose​

Create on-demand compute resources with automatic noBGP agent installation.

Input Schema​

{
  "node_name": "string (required)",
  "network_name": "string (optional)",
  "provider": "string (optional)",
  "cpu": "number (optional)",
  "memory": "number (optional)"
}

Parameters:

  • node_name - Name for the provisioned node
  • network_name - Target network. If omitted, the default network is used.
  • provider - Cloud provider: "aws" (default) or "cachengo"
  • cpu - CPU units (1024 = 1 vCPU). Default: 256 (0.25 vCPU). Range: 256-4096.
  • memory - Memory in MiB. Default: 512. Range: 512-16384.

Output Schema​

{
  "task_id": "string",
  "provider": "string",
  "resource_summary": "string",
  "notes": ["string"]
}

Example Usage​

Request:

{
  "node_name": "api-server-2",
  "network_name": "production",
  "cpu": 2048,
  "memory": 4096
}

Response:

{
  "task_id": "task_provisioning_123",
  "provider": "aws",
  "resource_summary": "2 vCPU, 4 GiB RAM",
  "notes": ["Node will appear in network_directory once online."]
}

Provisioning Flow​

  1. Request received and validated
  2. Container instance created on cloud provider
  3. noBGP agent installed and configured automatically
  4. Agent registers with your network
  5. Node appears as "online" in network_directory

Typical duration: 1-2 minutes

deprovision_node​

Terminate and remove a provisioned compute instance.

warning

Destructive operation. All data on the node will be permanently lost.

Purpose​

Remove provisioned infrastructure and stop billing.

Input Schema​

{
  "task_id": "string (required)"
}

Parameters:

  • task_id - Identifier of the provisioning task to deprovision (the UUID returned by provision_node)

Output Schema​

{
  "task_id": "string",
  "reference": "string",
  "provider": "string",
  "notes": ["string"]
}

Example Usage​

Request:

{
  "task_id": "task_provisioning_123"
}

Response:

{
  "task_id": "task_provisioning_123",
  "reference": "arn:aws:ecs:...",
  "provider": "aws",
  "notes": ["Task ran for 2h 15m before deprovisioning."]
}

Safety Features​

  • AI assistants typically ask user for confirmation first
  • Creates audit log entry

service_publish​

Publish a proxy or terminal service with a public HTTPS URL.

Purpose​

Expose HTTP applications or terminal access through secure public endpoints.

Service Mode​

The service mode is determined by which parameter is provided:

  • Proxy mode: Provide proxy_target_url (base64-encoded target URL)
  • Terminal mode: Provide terminal_command (command to run in the terminal)
  • Shell mode: Omit both to create a terminal running the default user shell

Input Schema​

{
  "network_name": "string (required)",
  "node_name": "string (required)",
  "title": "string (optional)",
  "proxy_target_url": "string (optional, base64-encoded)",
  "terminal_command": "string (optional)",
  "username": "string (optional)",
  "workdir": "string (optional)",
  "enabled": "boolean (optional, default: true)",
  "auth_required": "boolean (optional, default: true)"
}

Parameters:

  • network_name - Network where the agent resides
  • node_name - Agent name where the service will be published
  • title - Human-readable service name
  • proxy_target_url - Base64-encoded host/URI/port to proxy (e.g., aHR0cDovL2xvY2FsaG9zdDo4MDgw for http://localhost:8080). Mutually exclusive with terminal_command.
  • terminal_command - Command to expose via a web terminal. Mutually exclusive with proxy_target_url.
  • username - OS user for command execution (terminal/shell services only)
  • workdir - Working directory for command execution (terminal/shell services only)
  • enabled - Whether the service starts enabled (default: true)
  • auth_required - Whether OAuth is required to access (default: true)

Output Schema​

{
  "service_id": "string",
  "public_url": "string",
  "mode": "proxy|terminal"
}

Example Usage​

Proxy Service:

Request:

{
  "network_name": "production",
  "node_name": "web-server-1",
  "proxy_target_url": "aHR0cDovL2xvY2FsaG9zdDo4MDgw",
  "title": "staging-app",
  "auth_required": true
}

Response:

{
  "service_id": "svc_abc123",
  "public_url": "https://a1b2c3d4.nobgp.com",
  "mode": "proxy"
}

Terminal Service:

Request:

{
  "network_name": "production",
  "node_name": "raspberry-pi",
  "terminal_command": "bash",
  "username": "pi",
  "auth_required": true
}

Response:

{
  "service_id": "svc_def456",
  "public_url": "https://x9y8z7w6.nobgp.com",
  "mode": "terminal"
}

Default Shell Service:

Request:

{
  "network_name": "production",
  "node_name": "my-server",
  "auth_required": true
}

Response:

{
  "service_id": "svc_ghi789",
  "public_url": "https://p1q2r3s4.nobgp.com",
  "mode": "terminal"
}

service_update​

Modify an existing service's configuration.

Purpose​

Change service settings without deleting and recreating.

Input Schema​

{
  "service_id": "string (required)",
  "auth_required": "boolean (optional)",
  "enabled": "boolean (optional)",
  "title": "string (optional)",
  "proxy_target_url": "string (optional, base64-encoded)",
  "terminal_command": "string (optional)",
  "username": "string (optional)",
  "workdir": "string (optional)"
}

Parameters:

  • service_id - ID of the service to update
  • auth_required - Change authentication requirement
  • enabled - Enable or disable service
  • title - Update service display name
  • proxy_target_url - Update proxy target (base64-encoded URL). Switches service to proxy mode.
  • terminal_command - Update terminal command. Switches service to terminal mode.
  • username - Update OS user for command execution (terminal/shell services only)
  • workdir - Update working directory (terminal/shell services only)

Output Schema​

{
  "service_id": "string",
  "public_url": "string",
  "mode": "proxy|terminal",
  "title": "string",
  "enabled": "boolean",
  "auth_required": "boolean"
}

Example Usage​

Request:

{
  "service_id": "svc_abc123",
  "auth_required": false,
  "enabled": false
}

Response:

{
  "service_id": "svc_abc123",
  "public_url": "https://a1b2c3d4.nobgp.com",
  "mode": "proxy",
  "title": "staging-app",
  "enabled": false,
  "auth_required": false
}

service_delete​

Delete a published service.

Purpose​

Remove a service and free up its public URL.

Input Schema​

{
  "service_id": "string (required)"
}

Parameters:

  • service_id - ID of the service to delete

Output Schema​

{
  "service_id": "string",
  "mode": "string",
  "public_url": "string"
}

Example Usage​

Request:

{
  "service_id": "svc_abc123"
}

Response:

{
  "service_id": "svc_abc123",
  "mode": "proxy",
  "public_url": "https://a1b2c3d4.nobgp.com"
}

command​

Execute commands and manage interactive shell sessions on remote nodes.

Purpose​

Run one-shot commands or manage stateful interactive sessions. Use the session parameter to start a new command, then use the returned command_id for subsequent interactions (sending input, reading more output, or sending signals).

Input Schema​

{
  "command_id": "string (optional)",
  "session": {
    "network_name": "string (required)",
    "node_name": "string (required)",
    "command": "string (required)",
    "username": "string (optional)",
    "workdir": "string (optional)",
    "env": "object (optional)"
  },
  "input": "string (optional)",
  "raw": "boolean (optional)",
  "signal": "string (optional)",
  "idle_timeout": "number (optional)"
}

Parameters:

  • command_id - Session identifier from a previous call. Omit to create a new session.
  • session - Session creation parameters. Required when command_id is omitted.
    • network_name - Network where the node resides
    • node_name - Agent name to connect to
    • command - Command to execute (e.g., "bash", "df -h", "python3 script.py")
    • username - OS user to run as (defaults to agent's configured user)
    • workdir - Working directory (defaults to user's home directory)
    • env - Additional environment variables (e.g., {"DEBUG": "1"})
  • input - Text to send to stdin. C-style escape sequences (\n, \t, \xHH) are resolved by default. Set raw: true to disable.
  • raw - Send input bytes as-is without resolving escape sequences.
  • signal - Signal to send to the process: SIGINT, SIGTERM, SIGHUP, SIGQUIT, or SIGKILL.
  • idle_timeout - Seconds to wait with no output before returning (default: 5). Use 0 for non-blocking. Use higher values (e.g., 30 or 60) for slow commands. The command keeps running regardless.

Output Schema​

{
  "command_id": "string",
  "output": "string (omitted if empty)",
  "exit_code": "number (absent if still running)",
  "duration_ms": "number"
}

Fields:

  • command_id - Use this in subsequent calls to send more input or read more output
  • output - Captured stdout/stderr since the last call. Omitted if no output was produced.
  • exit_code - Present only when the command has exited (0 = success, non-zero = failure, -1 = killed by signal). Absence means the process is still running.
  • duration_ms - Wall-clock duration of this tool call in milliseconds.

Session Lifecycle​

Each command call runs one specific command. The session closes automatically when the command exits. A 30-second grace period allows reading the final exit code. For one-shot commands (ls, df -h, etc.), the session closes as soon as the command finishes.

Usage Patterns​

One-Shot Commands​

Start a command and read output in a single call:

Request:

{
  "session": {
    "network_name": "production",
    "node_name": "web-server-1",
    "command": "df -h"
  }
}

Response:

{
  "command_id": "cmd_abc123",
  "output": "Filesystem      Size  Used Avail Use% Mounted on\n/dev/sda1        50G   12G   36G  25% /\n",
  "exit_code": 0,
  "duration_ms": 312
}

Interactive Shell Sessions​

Start bash as the command to get an interactive shell, then send commands via input:

Start shell:

{
  "session": {
    "network_name": "production",
    "node_name": "web-server-1",
    "command": "bash"
  }
}

Response:

{
  "command_id": "cmd_xyz789",
  "output": "user@web-server-1:~$ ",
  "duration_ms": 145
}

Send a command:

{
  "command_id": "cmd_xyz789",
  "input": "cd /var/log && ls -lt | head -5\n"
}

Response:

{
  "command_id": "cmd_xyz789",
  "output": "total 1024\n-rw-r--r-- 1 root root 45234 Nov  4 14:32 syslog\n...\nuser@web-server-1:/var/log$ ",
  "duration_ms": 89
}

Close the shell:

{
  "command_id": "cmd_xyz789",
  "input": "exit\n"
}

Polling Long-Running Commands​

For commands that take a while, poll with command_id until exit_code appears:

Start:

{
  "session": {
    "network_name": "production",
    "node_name": "build-server",
    "command": "make build"
  },
  "idle_timeout": 30
}

Poll:

{
  "command_id": "cmd_build123",
  "idle_timeout": 30
}

Sending Signals​

Interrupt a running process:

{
  "command_id": "cmd_xyz789",
  "signal": "SIGINT"
}

register_node​

Generate install commands to connect an existing machine to a noBGP network.

Purpose​

Return ready-to-run shell commands for installing and configuring the noBGP agent on Linux, macOS, or Windows machines.

Input Schema​

{
  "network_name": "string (optional)",
  "node_name": "string (optional)"
}

Parameters:

  • network_name - Network to register the node into. If omitted, uses the default network.
  • node_name - Name for the node. If omitted, the machine's hostname is used.

Output Schema​

{
  "shell_install_command": "string",
  "power_shell_install_command": "string",
  "cmd_install_command": "string"
}

Fields:

  • shell_install_command — Shell command for Linux/macOS. Run this with sudo on the target machine to install and register the agent.
  • power_shell_install_command — PowerShell command for Windows. Run this in an elevated PowerShell session.
  • cmd_install_command — Command Prompt command for Windows CMD. Uses curl.exe (built-in since Windows 10 1803+). Run in an elevated Command Prompt.

Example Usage​

Request:

{
  "network_name": "production",
  "node_name": "web-server-1"
}

Response:

{
  "shell_install_command": "curl -fsSL https://downloads.nobgp.com/agent/install.sh | sudo NOBGP_KEY=VSH8vKlciUXLyFcnKptFBoQmhYQvq4PqC3/l0FrG/qQ= NOBGP_NAME=web-server-1 sh",
  "power_shell_install_command": "$env:NOBGP_KEY=\"VSH8vKlciUXLyFcnKptFBoQmhYQvq4PqC3/l0FrG/qQ=\"; $env:NOBGP_NAME=\"web-server-1\"; irm https://downloads.nobgp.com/agent/install.ps1 | iex",
  "cmd_install_command": "set \"NOBGP_KEY=VSH8vKlciUXLyFcnKptFBoQmhYQvq4PqC3/l0FrG/qQ=\" && set \"NOBGP_NAME=web-server-1\" && curl -fsSL https://downloads.nobgp.com/agent/install.cmd -o install.cmd && install.cmd"
}

Use Cases​

  • Connect an existing server, VM, or Raspberry Pi to noBGP
  • Onboard Windows machines via PowerShell (use power_shell_install_command) or Command Prompt (use cmd_install_command)
  • Automate agent installation in provisioning scripts

whoami​

Get information about the currently authenticated user.

Purpose​

Identity verification and session metadata.

Input Schema​

{}

No input parameters required.

Output Schema​

{
  "user_id": "string",
  "email": "string"
}

Example Usage​

Request:

{}

Response:

{
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com"
}

Error Handling​

All tools return errors in a consistent format:

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  }
}

Common Error Codes​

CodeDescriptionResolution
AUTH_REQUIREDNot authenticatedSign in via OAuth
PERMISSION_DENIEDInsufficient permissionsCheck account permissions
NOT_FOUNDResource doesn't existVerify resource name/ID
INVALID_INPUTBad request parametersCheck input schema
NETWORK_ERRORConnection failedCheck node is online
QUOTA_EXCEEDEDResource limit reachedUpgrade account or clean up
PROVISIONING_DISABLEDNo provisioning accessContact support

Example Error​

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "Node provisioning requires special account permissions",
    "details": {
      "required_permission": "node_provisioning",
      "contact": "support@nobgp.com"
    }
  }
}

Rate Limiting​

The MCP server implements rate limiting to ensure fair usage:

  • Discovery tools (network_directory, whoami): 60 requests/minute
  • Mutation tools (create, delete, update): 10 requests/minute
  • Session tools (command): 120 requests/minute
  • Provisioning tools: 5 requests/minute

Rate limit headers are included in responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1699105200

Best Practices​

1. Cache Directory Results​

Don't repeatedly call network_directory - cache results and refresh periodically.

2. Sessions Auto-Close​

Command sessions close automatically when the command exits — no need to explicitly close them. For interactive shell sessions (where you started bash), send exit\n via input or use signal: "SIGTERM" to end cleanly.

3. Use Descriptive Names​

Give networks, nodes, and services meaningful names for easier management.

4. Handle Errors Gracefully​

Check for error responses and handle them appropriately.

5. Respect Rate Limits​

Batch operations where possible and implement exponential backoff.

Next Steps​

Additional Resources​