MCP
Runix exposes process management operations through Model Context Protocol tools and resources.
Implementation
The implementation lives in runix/internal/mcp/.
| File | Responsibility |
|---|---|
server.go | MCP server construction and registration |
tools.go | Tool definitions |
handlers.go | Tool handlers backed by the supervisor |
resources.go | Resource and resource-template handlers |
transport_stdio.go | stdio transport |
transport_http.go | streamable HTTP transport |
Launch
# stdio transport
runix mcp
# HTTP transport
runix mcp --transport http --listen localhost:8090
If transport is omitted, Runix defaults to stdio.
Transports
stdio
Used for local AI agent integrations that spawn runix mcp as a subprocess.
HTTP
Used for remote or long-running integrations. The HTTP server listens on the configured address and logs /mcp as the endpoint.
When auth is enabled, HTTP requests are wrapped with the shared Runix auth middleware.
Tools
| Tool | Required Params | Optional Params | Description |
|---|---|---|---|
list_apps | none | none | List all managed processes |
start_app | entrypoint | name, runtime, cwd, restart_policy, env | Start a process |
stop_app | target | force | Stop a process by ID, name, or all |
restart_app | target | none | Restart a process |
reload_app | target | none | Gracefully reload a process |
delete_app | target | none | Stop and remove a process |
get_status | target | none | Return full process status |
get_logs | target | lines | Return recent process logs |
save_state | none | none | Persist current state to disk |
resurrect_processes | none | none | Restore previously saved state |
Resources
| Resource | Type | MIME Type | Description |
|---|---|---|---|
apps://list | static | application/json | All managed processes |
apps://{name} | template | application/json | One process by ID or name |
logs://{name} | template | text/plain | Recent log output |
metrics://{name} | template | application/json | Collected metrics for a process |
Example Configuration
mcp:
enabled: true
transport: stdio
listen: localhost:8090
security:
auth:
enabled: true
mode: token
token: "replace-with-a-long-random-token"
CLI flags override config values for transport and listen.
Notes
- MCP handlers call the supervisor directly, not the daemon IPC client
- Log and resource reads are capped to the last 1 MiB
- Metrics resources return a status object when collection is disabled or no sample exists yet