MCP
Oblien exposes two MCP servers so AI agents and IDE integrations can manage workspaces through a standard tool-calling interface.
| Server | Tools | Access |
|---|---|---|
| Control Plane | 81 | Remote — api.oblien.com/mcp (Streamable HTTP) or Local — npx oblien-mcp (stdio) |
| Runtime API | 23 | Gateway — workspace.oblien.com/mcp or Direct — VM:9990/mcp |
Architecture
┌───────────────────────────────────────────────────────────────────┐
│ AI Agent / IDE │
│ │
│ ┌──────────────────────────┐ ┌───────────────────────────────┐ │
│ │ Control Plane MCP │ │ Runtime MCP │ │
│ │ 81 tools │ │ 23 tools │ │
│ │ Workspace CRUD, │ │ Files, search, exec, │ │
│ │ lifecycle, network │ │ terminals, watchers │ │
│ └──────┬──────────┬────────┘ └──────┬──────────────┬─────────┘ │
│ │ │ │ │ │
│ (stdio) (HTTP) (gateway) (direct) │
└─────────┼──────────┼──────────────────┼──────────────┼───────────┘
│ │ │ │
▼ ▼ ▼ ▼
npx oblien-mcp api.oblien.com/mcp workspace. VM:9990
(local process) (remote) oblien.com (private IP)
│ │ │ │
└────┬─────┘ └──────┬───────┘
▼ ▼
api.oblien.com Workspace runtime
(manages all (runs inside a
workspaces) single workspace)Control Plane MCP — Create, start, stop, snapshot, monitor, and configure workspaces from outside. Two connection options:
- Remote — connect directly to
api.oblien.com/mcpfrom any HTTP-capable MCP client - Local — run
npx oblien-mcpas a stdio subprocess in your IDE
Both hit the same API and enforce the same auth. See Control Plane MCP.
Runtime MCP — Read/write files, run commands, manage terminals, and watch for filesystem changes inside a running workspace. Two access paths:
- Gateway —
workspace.oblien.com/mcpwith a Gateway JWT (same flow as the Runtime API) - Direct —
VM:9990/mcpwith a raw connection token (workspace-to-workspace over private network)
See Runtime MCP.
Quick start
Control Plane — Remote (Streamable HTTP)
Point any MCP client that supports HTTP transport at the remote endpoint:
URL: https://api.oblien.com/mcp
Auth: X-Client-ID / X-Client-Secret headersNo local install needed — the server is already running.
Control Plane — Local (stdio)
Run the MCP server as a local process for IDE integrations:
# Save credentials once
npx oblien config set --client-id "your-client-id" --client-secret "your-client-secret"
# Start the stdio server
npx oblien-mcpCredentials are stored in ~/.oblien/credentials.json and used automatically on every launch. See Control Plane MCP for IDE configs (VS Code, Cursor).
Runtime API
The MCP endpoint is at /mcp on the same server as the Runtime API REST endpoints — same two access paths, same auth:
Gateway: POST https://workspace.oblien.com/mcp (Gateway JWT)
Direct: POST http://10.x.x.x:9990/mcp (raw connection token)For setup (enabling the server, getting tokens, network config), see the Runtime API Access API reference. For the full MCP tool reference, see Runtime MCP.
Both MCP servers enforce the same authentication and authorization rules as their corresponding REST APIs. No permissions are bypassed.