Skip to main content

Agent Client Setup

This page shows how to connect Runix MCP to common coding agents and MCP-capable clients.

Pick A Transport​

Runix supports two MCP transport patterns:

  • stdio: the client launches runix mcp directly
  • http: Runix listens on an HTTP endpoint such as http://127.0.0.1:8090/mcp

Use stdio when the client can spawn local commands. Use http when the client prefers remote MCP servers or when you want one shared Runix MCP instance.

Runix MCP Commands​

Local stdio server:

runix mcp

HTTP server:

runix mcp --transport http --listen 127.0.0.1:8090

If you use HTTP transport, keep that process running while the client is connected.

Codex​

Codex can register MCP servers with the CLI and shares that configuration with the IDE extension.

Stdio Setup​

codex mcp add runix -- runix mcp
codex mcp list

HTTP Setup​

Start Runix first:

runix mcp --transport http --listen 127.0.0.1:8090

Then register it:

codex mcp add runix --url http://127.0.0.1:8090/mcp
codex mcp list

Direct Config​

You can also add Runix to ~/.codex/config.toml:

[mcp_servers.runix]
command = "runix"
args = ["mcp"]

Or for HTTP:

[mcp_servers.runix]
url = "http://127.0.0.1:8090/mcp"

Claude Code​

Claude Code supports project-scoped and user-scoped MCP registrations.

Stdio Setup​

Project-scoped:

claude mcp add --transport stdio runix -- runix mcp

User-scoped:

claude mcp add --transport stdio --scope user runix -- runix mcp

HTTP Setup​

Start Runix first:

runix mcp --transport http --listen 127.0.0.1:8090

Then register it:

claude mcp add --transport http runix http://127.0.0.1:8090/mcp

Verify:

claude mcp get runix
claude mcp list

Project File​

Claude Code project registrations are written in .mcp.json. A direct config looks like:

{
  "mcpServers": {
    "runix": {
      "command": "runix",
      "args": ["mcp"],
      "env": {}
    }
  }
}

OpenCode​

OpenCode supports both local and remote MCP servers in opencode.jsonc.

Local Setup​

Create or update opencode.jsonc in the project:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "runix": {
      "type": "local",
      "command": ["runix", "mcp"],
      "enabled": true
    }
  }
}

Remote Setup​

Start Runix first:

runix mcp --transport http --listen 127.0.0.1:8090

Then configure OpenCode:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "runix": {
      "type": "remote",
      "url": "http://127.0.0.1:8090/mcp",
      "enabled": true
    }
  }
}

OpenCode also provides an interactive helper:

opencode mcp add
opencode mcp list

Generic MCP Client​

For clients that use a JSON MCP server map, these are the two common Runix forms.

Stdio:

{
  "mcpServers": {
    "runix": {
      "command": "runix",
      "args": ["mcp"]
    }
  }
}

HTTP:

{
  "mcpServers": {
    "runix": {
      "url": "http://127.0.0.1:8090/mcp"
    }
  }
}

If your client supports project instructions such as AGENTS.md, add a short rule so the agent knows when to use Runix:

Use the `runix` MCP server when you need to inspect, start, stop, restart, or read logs from managed processes.

Available Runix MCP Surface​

Once connected, these tools are available:

  • list_apps
  • start_app
  • stop_app
  • restart_app
  • reload_app
  • delete_app
  • get_status
  • get_logs
  • save_state
  • resurrect_processes

And these resources:

  • apps://list
  • apps://{name}
  • logs://{name}
  • metrics://{name}