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 10 MCP tools organized by function:

Network Management:

• network_directory - Discovery and listing
• network_create - Create networks
• network_delete - Delete networks

Node Provisioning:

• provision_node - Create compute resources
• deprovision_node - Remove compute resources

Service Publishing:

• service_publish - Expose services publicly
• service_update - Modify service settings
• service_delete - Remove services

Interactive Sessions:

• tty_exchange - Shell session management

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": "string (optional)"
}

Parameters:

• network - Specific network name to query. If omitted, returns all networks.

Output Schema

{
  "networks": [
    {
      "name": "string",
      "id": "string",
      "created": "timestamp",
      "nodes": [
        {
          "name": "string",
          "status": "online|offline|connecting",
          "os": "string",
          "arch": "string",
          "ip_addresses": ["string"],
          "last_seen": "timestamp"
        }
      ],
      "services": [
        {
          "id": "string",
          "url": "string",
          "type": "proxy|terminal",
          "node": "string",
          "auth_required": "boolean",
          "enabled": "boolean"
        }
      ]
    }
  ]
}

Example Usage

Request:

{
  "network": "production"
}

Response:

{
  "networks": [
    {
      "name": "production",
      "id": "net_abc123",
      "created": "2024-10-15T09:00:00Z",
      "nodes": [
        {
          "name": "web-server-1",
          "status": "online",
          "os": "Ubuntu 22.04",
          "arch": "amd64",
          "ip_addresses": ["10.0.1.5", "203.0.113.42"],
          "last_seen": "2024-11-04T14:30:00Z"
        }
      ],
      "services": [
        {
          "id": "svc_xyz789",
          "url": "https://abc123.nobgp.com",
          "type": "proxy",
          "node": "web-server-1",
          "auth_required": true,
          "enabled": true
        }
      ]
    }
  ]
}

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)",
  "description": "string (optional)"
}

Parameters:

• name - Unique name for the network (alphanumeric, hyphens, underscores)
• description - Human-readable description

Output Schema

{
  "network": {
    "name": "string",
    "id": "string",
    "network_key": "string (base64)",
    "created": "timestamp"
  }
}

Example Usage

Request:

{
  "name": "staging",
  "description": "Staging environment for testing"
}

Response:

{
  "network": {
    "name": "staging",
    "id": "net_def456",
    "network_key": "VSH8vKlciUXLyFcnKptFBoQmhYQvq4PqC3/l0FrG/qQ=",
    "created": "2024-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 a network and disconnect all associated nodes.

warning

Destructive operation. All nodes will be disconnected, and services will be deleted.

Input Schema

{
  "network": "string (required)",
  "confirm": "boolean (required)"
}

Parameters:

• network - Name of the network to delete
• confirm - Must be true to proceed (safety mechanism)

Output Schema

{
  "success": "boolean",
  "deleted_network": "string",
  "disconnected_nodes": "number",
  "deleted_services": "number"
}

Example Usage

Request:

{
  "network": "old-testing",
  "confirm": true
}

Response:

{
  "success": true,
  "deleted_network": "old-testing",
  "disconnected_nodes": 3,
  "deleted_services": 2
}

Safety Features

• Requires explicit confirmation (confirm: true)
• AI assistants typically ask user for confirmation 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

{
  "network": "string (optional)",
  "name": "string (optional)",
  "os": "string (optional)",
  "provider": "string (optional)",
  "region": "string (optional)",
  "vcpu": "number (optional)",
  "memory_gb": "number (optional)",
  "disk_gb": "number (optional)"
}

Parameters:

• network - Target network (defaults to "default")
• name - Node name (auto-generated if omitted)
• os - Operating system: "ubuntu", "debian", "alpine", "amazonlinux"
• provider - Cloud provider: "aws" (more coming soon)
• region - Provider-specific region (e.g., "us-east-1")
• vcpu - Number of virtual CPUs
• memory_gb - RAM in gigabytes
• disk_gb - Storage in gigabytes

Output Schema

{
  "task_id": "string",
  "status": "pending|provisioning|online|failed",
  "node": {
    "name": "string",
    "provider": "string",
    "instance_type": "string",
    "region": "string",
    "network": "string",
    "estimated_time": "duration"
  }
}

Example Usage

Request:

{
  "network": "production",
  "name": "api-server-2",
  "os": "ubuntu",
  "vcpu": 2,
  "memory_gb": 4,
  "region": "us-east-1"
}

Response:

{
  "task_id": "task_provisioning_123",
  "status": "provisioning",
  "node": {
    "name": "api-server-2",
    "provider": "aws",
    "instance_type": "t3.medium",
    "region": "us-east-1",
    "network": "production",
    "estimated_time": "120s"
  }
}

Provisioning Flow

1. Request received and validated
2. Cloud instance created
3. Operating system installed
4. noBGP agent installed automatically
5. Agent configured with network key
6. Node joins network
7. Status updates to "online"

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

{
  "node": "string (required)",
  "network": "string (optional)",
  "confirm": "boolean (required)"
}

Parameters:

• node - Name of the node to deprovision
• network - Network name (helps disambiguate if same node name exists in multiple networks)
• confirm - Must be true to proceed

Output Schema

{
  "success": "boolean",
  "node": "string",
  "provider": "string",
  "instance_id": "string",
  "terminated_at": "timestamp"
}

Example Usage

Request:

{
  "node": "temp-dev-server",
  "network": "development",
  "confirm": true
}

Response:

{
  "success": true,
  "node": "temp-dev-server",
  "provider": "aws",
  "instance_id": "i-0abc123def456",
  "terminated_at": "2024-11-04T15:00:00Z"
}

Safety Features

• Requires explicit confirmation
• Cannot deprovision nodes with active services (must delete services 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.

Input Schema

{
  "node": "string (required)",
  "type": "proxy|terminal (required)",
  "target": "string (required for proxy)",
  "name": "string (optional)",
  "auth_required": "boolean (optional, default: true)",
  "network": "string (optional)"
}

Parameters:

• node - Node to publish service from
• type - Service type: "proxy" or "terminal"
• target - For proxy type: URL to proxy (e.g., "http://localhost:8080")
• name - Human-readable service name
• auth_required - Whether OAuth is required to access (default: true)
• network - Network name (if ambiguous)

Output Schema

{
  "service": {
    "id": "string",
    "url": "string",
    "type": "string",
    "node": "string",
    "target": "string",
    "auth_required": "boolean",
    "enabled": "boolean",
    "created": "timestamp"
  }
}

Example Usage

Proxy Service:

Request:

{
  "node": "web-server-1",
  "type": "proxy",
  "target": "http://localhost:8080",
  "name": "staging-app",
  "auth_required": true
}

Response:

{
  "service": {
    "id": "svc_abc123",
    "url": "https://a1b2c3d4.nobgp.com",
    "type": "proxy",
    "node": "web-server-1",
    "target": "http://localhost:8080",
    "auth_required": true,
    "enabled": true,
    "created": "2024-11-04T15:05:00Z"
  }
}

Terminal Service:

Request:

{
  "node": "raspberry-pi",
  "type": "terminal",
  "auth_required": true
}

Response:

{
  "service": {
    "id": "svc_def456",
    "url": "https://x9y8z7w6.nobgp.com",
    "type": "terminal",
    "node": "raspberry-pi",
    "auth_required": true,
    "enabled": true,
    "created": "2024-11-04T15:06:00Z"
  }
}

---

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)",
  "target": "string (optional, proxy only)"
}

Parameters:

• service_id - ID of the service to update
• auth_required - Change authentication requirement
• enabled - Enable or disable service
• target - Update proxy target URL

Output Schema

{
  "service": {
    "id": "string",
    "updated_fields": ["string"],
    "...service details..."
  }
}

Example Usage

Request:

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

Response:

{
  "service": {
    "id": "svc_abc123",
    "updated_fields": ["auth_required", "enabled"],
    "auth_required": false,
    "enabled": 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

{
  "success": "boolean",
  "deleted_service_id": "string",
  "deleted_url": "string"
}

Example Usage

Request:

{
  "service_id": "svc_abc123"
}

Response:

{
  "success": true,
  "deleted_service_id": "svc_abc123",
  "deleted_url": "https://a1b2c3d4.nobgp.com"
}

---

tty_exchange

Create and interact with interactive shell sessions.

Purpose

Manage stateful terminal sessions for command execution.

Input Schema

{
  "node": "string (required)",
  "network": "string (optional)",
  "session_id": "string (optional)",
  "input": "string (optional)",
  "control": "string (optional)",
  "action": "create|send|close (optional)"
}

Parameters:

• node - Target node name
• network - Network name (if ambiguous)
• session_id - Existing session ID (for ongoing sessions)
• input - Command or text to send to session
• control - Control character (e.g., "^C", "^D")
• action - Session action: "create", "send", "close"

Output Schema

{
  "session_id": "string",
  "output": "string",
  "exit_code": "number (if command completed)",
  "prompt": "string",
  "status": "active|closed"
}

Example Usage

Create Session:

Request:

{
  "node": "web-server-1",
  "action": "create"
}

Response:

{
  "session_id": "sess_xyz789",
  "output": "user@web-server-1:~$",
  "prompt": "user@web-server-1:~$",
  "status": "active"
}

Send Command:

Request:

{
  "session_id": "sess_xyz789",
  "action": "send",
  "input": "ls -la\n"
}

Response:

{
  "session_id": "sess_xyz789",
  "output": "total 48\ndrwxr-xr-x 5 user user 4096 Nov  4 10:30 .\ndrwxr-xr-x 3 root root 4096 Oct 15 09:00 ..\n...",
  "prompt": "user@web-server-1:~$",
  "status": "active"
}

Close Session:

Request:

{
  "session_id": "sess_xyz789",
  "action": "close"
}

Response:

{
  "session_id": "sess_xyz789",
  "status": "closed"
}

Session Features

• Persistent environment (cd, export, etc.)
• Full terminal emulation (colors, control characters)
• Timeout after 30 minutes of inactivity
• Support for interactive programs (vim, htop, etc.)

---

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",
    "name": "string",
    "provider": "string",
    "permissions": ["string"],
    "default_network": "string",
    "account_created": "timestamp"
  },
  "session": {
    "authenticated_at": "timestamp",
    "expires_at": "timestamp",
    "token_age": "duration"
  }
}

Example Usage

Request:

{}

Response:

{
  "user": {
    "id": "user_abc123",
    "email": "user@example.com",
    "name": "Jane Doe",
    "provider": "google",
    "permissions": ["network_management", "node_provisioning"],
    "default_network": "production",
    "account_created": "2024-09-15T10:00:00Z"
  },
  "session": {
    "authenticated_at": "2024-11-04T14:00:00Z",
    "expires_at": "2024-11-04T18:00:00Z",
    "token_age": "45m"
  }
}

---

Error Handling

All tools return errors in a consistent format:

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

Common Error Codes

Code	Description	Resolution
AUTH_REQUIRED	Not authenticated	Sign in via OAuth
PERMISSION_DENIED	Insufficient permissions	Check account permissions
NOT_FOUND	Resource doesn't exist	Verify resource name/ID
INVALID_INPUT	Bad request parameters	Check input schema
NETWORK_ERROR	Connection failed	Check node is online
QUOTA_EXCEEDED	Resource limit reached	Upgrade account or clean up
PROVISIONING_DISABLED	No provisioning access	Contact 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 (tty_exchange): 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. Close Sessions

Always close tty sessions when done to free up resources.

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

• Core Concepts - Understand the underlying architecture
• Use Cases & Examples - See tools in action
• ChatGPT Setup - Use via ChatGPT Actions API
• Claude Setup - Use via Claude MCP client

Additional Resources

• MCP Specification - Learn about the protocol
• noBGP Web Dashboard - Alternative management interface
• OpenAPI Schema - For Actions API