MCP Integration

RunOS provides native support for the Model Context Protocol (MCP), enabling AI coding assistants to directly interact with your infrastructure. This allows AI tools like Claude Code, Roo Code, and OpenAI Codex to query your clusters, manage services, and perform infrastructure operations through natural language.

What is MCP?

The Model Context Protocol is an open standard for connecting AI assistants to external tools and data sources. When you configure RunOS MCP servers, your AI assistant gains the ability to:

• Query cluster status and health
• List and inspect services
• Create, update, and delete resources
• Retrieve connection credentials
• Manage applications and deployments

All operations use the same secure API as the CLI and Console.

MCP Servers

RunOS provides four separate MCP servers, each with different permission levels. This separation allows you to grant AI assistants only the access they need.

Server	Command	Description
runos	runos mcp serve read	Read-only operations (query infrastructure)
runos-sensitive-read	runos mcp serve sensitive-read	Access sensitive data (passwords, credentials)
runos-write	runos mcp serve write	Create, update, delete operations
runos-sensitive-write	runos mcp serve sensitive-write	Credential rotation, secret management

Permission Levels

Read (safest)

• List clusters, nodes, services
• View configurations and status
• Check application health
• No modifications possible

Sensitive Read

• Everything in Read
• Access database passwords
• View connection strings
• Retrieve API keys

Write

• Create new services
• Update configurations
• Delete resources
• Deploy applications

Sensitive Write

• Rotate credentials
• Manage secrets
• Perform security-critical operations

Understanding "Sensitive" Servers

When using sensitive-read or sensitive-write servers, sensitive information like database passwords and connection strings will travel through the LLM. Only enable these servers when you specifically need credential access.

Configuring AI Assistants

RunOS can automatically generate configuration files for popular AI coding tools.

Claude Code

runos mcp configure claude

This creates two files in your project:

.mcp.json - MCP server definitions:

{
  "mcpServers": {
    "runos": {
      "type": "stdio",
      "command": "/path/to/runos",
      "args": ["mcp", "serve", "read"],
      "env": {}
    },
    "runos-sensitive-read": {
      "type": "stdio",
      "command": "/path/to/runos",
      "args": ["mcp", "serve", "sensitive-read"],
      "env": {}
    },
    "runos-write": {
      "type": "stdio",
      "command": "/path/to/runos",
      "args": ["mcp", "serve", "write"],
      "env": {}
    },
    "runos-sensitive-write": {
      "type": "stdio",
      "command": "/path/to/runos",
      "args": ["mcp", "serve", "sensitive-write"],
      "env": {}
    }
  }
}

.claude/settings.json - Permission settings:

{
  "permissions": {
    "allow": ["mcp__runos__*"]
  }
}

This configuration only auto-allows the read-only runos server (tools prefixed with mcp__runos__). The other three servers use different prefixes (mcp__runos-sensitive-read__, mcp__runos-write__, mcp__runos-sensitive-write__) and will prompt for your confirmation before executing any operations.

Roo Code

runos mcp configure roo

Creates .roo/mcp.json with server definitions and tool allowlists.

OpenAI Codex

runos mcp configure codex

Creates .codex/config.toml with MCP server configuration.

Warning: The RunOS MCP integration requires Codex to run outside of its sandbox (Codex defaults to sandbox mode). This gives Codex full access to execute commands without permission prompts. Use with caution and consider running Codex inside a VM or Docker container for added isolation.

Usage Examples

Once configured, you can interact with RunOS through natural language:

Querying infrastructure:

"What services are running in my production cluster?"

Getting connection details:

"Give me the PostgreSQL connection string for the users-db service"

Creating resources:

"Create a new Valkey cache called session-store with 2 replicas"

Troubleshooting:

"Show me the status of all nodes in cluster i4y"

Running database queries:

"Show me a database view of all users and the count of their posts"

Managing object storage:

"Create a new bucket in my object store that can be accessed by the public"

Database administration:

"Create a new database and user on my PostgreSQL instance"

The AI assistant translates these requests into the appropriate MCP tool calls, including executing SQL queries against your databases through RunOS.

Troubleshooting

Server Not Starting

Ensure you're authenticated:

runos login

Tools Not Appearing

Update your manifest:

runos manifest update

Permission Denied

Check that the correct MCP server is enabled for the operation you're attempting. Write operations require the write or sensitive-write servers.

Configuration Not Loading

Verify your configuration file paths:

• Claude Code: .mcp.json and .claude/settings.json in project root
• Roo Code: .roo/mcp.json in project root
• Codex: .codex/config.toml in project root

Note on Documentation Currency

Like the CLI, MCP tools are dynamically generated and automatically kept in sync with the RunOS API. As RunOS evolves, new tools become available automatically. Documentation may occasionally lag behind the latest available tools.