Runtime MCP

The Runtime MCP endpoint runs inside each workspace on port 9990. It provides 23 tools for file operations, search, command execution, terminal sessions, and filesystem watchers — the same operations available through the Runtime API REST endpoints.

This is a pure JSON-RPC 2.0 implementation with zero external dependencies. It dispatches tool calls internally to the same handlers that serve the REST API.

Connection

The MCP endpoint lives on the same server as the Runtime API REST endpoints — same access paths, same auth, just a different URL path (/mcp instead of /files, /exec, etc.).

Access method	MCP URL	Auth	Setup guide
Gateway	`https://workspace.oblien.com/mcp`	Gateway JWT	Runtime API — Gateway access
Direct	`http://10.x.x.x:9990/mcp`	Raw connection token	Runtime API — Direct access

For how to enable the server, get tokens, and configure network access, see the Runtime API Access API reference.

Example — Gateway

Once you have a Gateway JWT (how to get one):

curl -X POST https://workspace.oblien.com/mcp \
  -H "Authorization: Bearer $GATEWAY_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

Example — Direct

Once you have a raw connection token (how to get one) and a private link:

curl -X POST http://10.x.x.x:9990/mcp \
  -H "Authorization: Bearer $RAW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

Request format

Standard JSON-RPC 2.0:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

Supported methods

Method	Description
`initialize`	MCP handshake (returns server info and capabilities)
`tools/list`	List all available tools
`tools/call`	Call a tool

Debug endpoint

A GET /mcp endpoint is available for quick verification:

# Via gateway
curl https://workspace.oblien.com/mcp \
  -H "Authorization: Bearer $GATEWAY_JWT"

# Direct
curl http://10.x.x.x:9990/mcp \
  -H "Authorization: Bearer $RAW_TOKEN"

Returns the tool count and server version.

Tool reference

All 23 tools are listed below. Each tool maps to a REST endpoint documented in the Runtime API Reference.

Files (6 tools)

Read, write, and manage files inside the workspace.

Tool	Description	REST equivalent
`file_list`	List directory contents with metadata. Supports recursion, gitignore filtering, inline content, and hash computation.	`GET /files`
`file_read`	Read file content as UTF-8 text. Supports line ranges and line numbers. Max 10 MiB.	`GET /files/read`
`file_write`	Write content to a file. Creates parent directories if needed. Supports append mode.	`POST /files/write`
`file_mkdir`	Create a directory (with parents).	`POST /files/mkdir`
`file_stat`	Get file metadata: size, type, permissions, modified time, symlink target.	`GET /files/stat`
`file_delete`	Delete a file or directory.	`DELETE /files/delete`

`file_list` parameters

Parameter	Type	Description
`path`	string	Directory path (default: `/`)
`nested`	boolean	Recurse into subdirectories
`light`	boolean	Minimal output (names only)
`include_hash`	boolean	Include SHA-256 hash per file
`include_content`	boolean	Inline file content
`code_files_only`	boolean	Filter to code files
`flatten`	boolean	Flat list instead of tree
`use_gitignore`	boolean	Respect `.gitignore` rules
`max_depth`	number	Maximum recursion depth
`ignore_patterns`	string[]	Glob patterns to exclude
`path_filter`	string	Filter paths by substring
`include_ext`	string[]	Only include these extensions

`file_read` parameters

Parameter	Type	Required	Description
`path`	string	yes	File path
`start_line`	number	no	First line to read (1-based)
`end_line`	number	no	Last line to read (1-based)
`with_line_numbers`	boolean	no	Prefix lines with numbers

`file_write` parameters

Parameter	Type	Required	Description
`path`	string	yes	File path
`content`	string	yes	File content
`create_dirs`	boolean	no	Create parent directories
`append`	boolean	no	Append instead of overwrite
`mode`	string	no	File permissions (e.g. `"0644"`)

Search (3 tools)

Full-text content search and file name search.

Tool	Description	REST equivalent
`search_content`	Search file contents using ripgrep. Returns matches grouped by file with line, column, and text.	`GET /files/search`
`search_files`	Search for files by name. Pure Go implementation, no ripgrep needed. Respects `.gitignore`.	`GET /files/search/files`
`search_init`	Check if ripgrep is installed, or trigger installation.	`POST /files/search/init`

`search_content` parameters

Parameter	Type	Required	Description
`q`	string	yes	Search query
`path`	string	no	Directory to search in
`case_sensitive`	boolean	no	Case-sensitive matching
`regex`	boolean	no	Treat query as regex
`whole_word`	boolean	no	Match whole words only
`max_results`	number	no	Limit number of results
`timeout`	number	no	Timeout in seconds
`context_lines`	number	no	Lines of context around matches
`ignore_patterns`	string[]	no	Patterns to exclude
`file_types`	string[]	no	File extensions to include
`include_hidden`	boolean	no	Include hidden files

Exec (6 tools)

Execute commands and manage task lifecycles.

Tool	Description	REST equivalent
`exec_run`	Execute a command synchronously. Returns stdout, stderr, exit code.	`POST /exec`
`exec_list`	List all exec tasks.	`GET /exec`
`exec_get`	Get task details by ID.	`GET /exec/:id`
`exec_input`	Send stdin to a running task.	`POST /exec/:id/input`
`exec_delete`	Delete a task.	`DELETE /exec/:id`
`exec_delete_all`	Delete all tasks.	`DELETE /exec`

`exec_run` parameters

Parameter	Type	Required	Description
`command`	string[]	yes	Command as array (exec'd directly, no shell)
`timeout_seconds`	number	no	Kill after N seconds
`keep_logs`	boolean	no	Retain stdout/stderr after completion
`exec_mode`	string	no	Execution mode

Commands are executed directly without a shell. To use shell features (pipes, redirects), pass ["sh", "-c", "your command | here"].

Terminals (4 tools)

Create and manage PTY terminal sessions. Terminal I/O flows over WebSocket at /ws.

Tool	Description	REST equivalent
`terminal_create`	Create a new PTY session.	`POST /terminals`
`terminal_list`	List active sessions.	`GET /terminals`
`terminal_scrollback`	Get terminal output history (base64-encoded).	`GET /terminals/:id/scrollback`
`terminal_delete`	Kill and close a session.	`DELETE /terminals/:id`

`terminal_create` parameters

Parameter	Type	Description
`command`	string[]	Shell command (default: system shell)
`cols`	number	Terminal width
`rows`	number	Terminal height
`scrollback_size`	number	Scrollback buffer size in bytes

Watchers (4 tools)

Recursive filesystem watchers using inotify. Events are delivered over WebSocket.

Tool	Description	REST equivalent
`watcher_create`	Create a recursive file watcher.	`POST /watchers`
`watcher_list`	List active watchers.	`GET /watchers`
`watcher_get`	Get watcher details.	`GET /watchers/:id`
`watcher_delete`	Stop and remove a watcher.	`DELETE /watchers/:id`

`watcher_create` parameters

Parameter	Type	Required	Description
`path`	string	yes	Directory to watch
`excludes`	string[]	no	Patterns to exclude from watching

Example: full workflow

Create a file, verify it exists, then search its content — all through MCP tool calls:

// 1. Write a file
{
  "jsonrpc": "2.0", "id": 1,
  "method": "tools/call",
  "params": {
    "name": "file_write",
    "arguments": {
      "path": "/home/user/hello.py",
      "content": "print('hello world')\n",
      "create_dirs": true
    }
  }
}

// 2. Verify it exists
{
  "jsonrpc": "2.0", "id": 2,
  "method": "tools/call",
  "params": {
    "name": "file_stat",
    "arguments": { "path": "/home/user/hello.py" }
  }
}

// 3. Run it
{
  "jsonrpc": "2.0", "id": 3,
  "method": "tools/call",
  "params": {
    "name": "exec_run",
    "arguments": {
      "command": ["python3", "/home/user/hello.py"]
    }
  }
}

Limits

Limit	Value
Max request body	4 MiB
Max file read	10 MiB
Session header	`Mcp-Session-Id` (optional, echoed back)

Error handling

Errors follow JSON-RPC 2.0 conventions:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "unknown tool: foo_bar"
  }
}

Code	Meaning
`-32700`	Parse error (invalid JSON)
`-32601`	Method not found
`-32602`	Invalid params / unknown tool
`-32603`	Internal error (tool execution failed)

On this page