Control Plane MCP

The control plane MCP server exposes 81 tools that map 1-to-1 with the REST API. Every tool runs through the same shared action layer, so authentication, authorization, and validation are identical on both transports.

Connection

Two ways to connect — use whichever fits your client:

Both methods hit the same 81 tools with identical auth and validation.

Remote — Streamable HTTP

The control plane MCP server is available as a remote HTTP endpoint. Any MCP client that supports Streamable HTTP transport can connect directly — no local install required.

Endpoint: https://api.oblien.com/mcp

Authentication: Include your API credentials as HTTP headers on every request:

X-Client-ID: your-client-id
X-Client-Secret: your-client-secret

Or use a bearer token:

Authorization: Bearer <token>

Example — list tools:

curl -X POST https://api.oblien.com/mcp \
  -H "X-Client-ID: your-client-id" \
  -H "X-Client-Secret: your-client-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

MCP client config (HTTP transport):

{
  "mcpServers": {
    "oblien": {
      "url": "https://api.oblien.com/mcp",
      "headers": {
        "X-Client-ID": "your-client-id",
        "X-Client-Secret": "your-client-secret"
      }
    }
  }
}

Local — Stdio

Run the MCP server as a local subprocess. This is the standard for IDE integrations — the server reads stdin/writes stdout.

Setup credentials (one-time):

npx oblien config set --client-id "your-client-id" --client-secret "your-client-secret"

Credentials are stored in ~/.oblien/credentials.json (mode 0600, private to your user). Once saved, oblien-mcp picks them up automatically.

Run the server:

npx oblien-mcp

Alternatively, pass credentials via environment variables (useful for CI or ephemeral environments):

export OBLIEN_CLIENT_ID="your-client-id"
export OBLIEN_CLIENT_SECRET="your-client-secret"
npx oblien-mcp

IDE configuration

VS Code (Claude / Copilot)

Add to your .vscode/mcp.json:

{
  "servers": {
    "oblien": {
      "command": "npx",
      "args": ["oblien-mcp"]
    }
  }
}

Alternatively, pass credentials explicitly:

{
  "servers": {
    "oblien": {
      "command": "npx",
      "args": ["oblien-mcp"],
      "env": {
        "OBLIEN_CLIENT_ID": "your-client-id",
        "OBLIEN_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Cursor

Add to your Cursor MCP settings:

{
  "mcpServers": {
    "oblien": {
      "command": "npx",
      "args": ["oblien-mcp"]
    }
  }
}

Or with explicit env vars:

{
  "mcpServers": {
    "oblien": {
      "command": "npx",
      "args": ["oblien-mcp"],
      "env": {
        "OBLIEN_CLIENT_ID": "your-client-id",
        "OBLIEN_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Tool reference

All 81 tools are listed below, grouped by category. Each tool maps to a REST endpoint documented in the API Reference.

Tools

Core (10 tools)

Workspace CRUD, quota, and usage overview.

Overlay / Filesystem (6 tools)

Read, write, and manage the workspace overlay filesystem.

Power (5 tools)

Start, stop, pause, resume, and restart workspaces.

Lifecycle (6 tools)

Control workspace lifetime, TTL, and permanent/temporary status.

Logs (5 tools)

Retrieve and manage workspace logs.

Metrics (3 tools)

System info, config, and real-time stats.

Network (3 tools)

Network policy and outbound IP configuration.

Snapshots & Archives (7 tools)

Point-in-time snapshots and long-term archives.

SSH (5 tools)

SSH access management.

Workloads (11 tools)

Manage long-running processes inside workspaces.

Metadata (2 tools)

Custom key-value metadata on workspaces.

Resources (2 tools)

CPU, memory, and disk resource allocation.

Usage (6 tools)

Per-workspace billing, usage tracking, and credits.

Public Access (3 tools)

Expose workspace ports to the internet.

Runtime API Access (6 tools)

Enable and manage the HTTP API running inside workspaces.

Details (1 tool)

Namespaces

All tools operate within the authenticated user's namespace by default. To target a specific namespace, pass namespace as a tool parameter:

{
  "name": "workspace_list",
  "arguments": {
    "namespace": "team-backend"
  }
}

The API key must have permission on the target namespace.

Error handling

Tool calls that fail return a standard MCP error object:

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "{\"error\":\"workspace_not_found\",\"message\":\"Workspace ws_abc123 not found\"}"
    }
  ]
}

HTTP status codes from the underlying API are mapped to descriptive error messages. Common errors: