MCP reference

An MCP server that sits between your agent and your infrastructure.

OpsMaxx exposes 28 tools over MCP. An agent addresses a server by the friendly name you gave it, never a hostname; OpsMaxx resolves the real connection from your OS keychain, applies the access group, and redacts the output before the agent sees it.

One request, end to end

The same path whether the client speaks HTTP or stdio. Nothing about the policy changes because of how an agent connected.

  1. Agent asks

    execute_command on "Nginx Prod"

  2. Policy check

    access group says ALLOW, ASK or DENY

  3. You approve

    ASK waits in Approvals; the agent waits too

  4. OpsMaxx connects

    real host and key read from the OS keychain

  5. Output redacted

    secrets and secret-shaped strings stripped

  6. Written down

    agent, server, action and result in the audit log

Every capability is ALLOW, ASK or DENY

An access group is not a single on/off switch. Each capability is set independently, and file paths can be overridden on top of the blanket read and write settings. Four groups ship with the app — Read Only, Read & Write, Sudo Access, Full Access — and you can create as many as you want.

ALLOW

Runs immediately, and is written to the audit log.

ASK

Waits in Approvals. The agent blocks until you answer.

DENY

Refused. The agent is told it was refused, and why.

The 28 tools an agent can call

Each one is governed separately by the access group. Summaries here are condensed from the descriptions the server sends to the client, so an agent and a reader are told the same thing.

Servers

list_servers
The servers this session may use, by friendly name, grouped by workspace. Every other tool addresses a server by one of these names — a hostname or IP will not resolve.
get_server_details
The OS, access group and the effective permissions this session has on one server.
get_host_facts
What a server is rather than what it is doing: distribution, version, kernel, package manager.
get_server_metrics
CPU, memory, disk, uptime and any failed systemd units.
execute_command
One non-interactive command over SSH, returning stdout, stderr and the exit code. Escalation shells are refused.
add_server
Adds a new SSH connection to a workspace, so later calls can address it by name.
describe_capabilities
What this session may and may not do on a server — designed to be called before trying.
list_workspaces
The workspaces this session can see.

Files

list_files
A directory over SFTP, with sizes and types.
read_file
A text file over SFTP. Preferred over running cat through a shell.
write_file
Writes a text file over SFTP, replacing it entirely.

Containers

list_containers
Containers on one server: name, image, state and the status line the runtime wrote.
container_logs
The last lines a container wrote to stdout and stderr.
container_action
Starts, stops or restarts one container.
list_images
Images on a server: repository, tag, id and the size the runtime reports.
compose_status
Containers grouped by compose project and service.

Databases

list_databases
The database connections this session may use, by friendly name.
query_database
Runs a statement against a saved connection and returns the rows.

Network

list_tunnels
The SSH tunnels configured in this session.
set_tunnel
Starts or stops a tunnel that is already configured.
list_vpns
The VPN profiles this session can see.
set_vpn
Starts or stops a VPN that is already configured.

Fleet

fleet_inventory
One answer for every server in the workspace, from what has already been collected.
fleet_drift
Every server whose watched configuration no longer matches its baseline.
get_config_drift
Whether the watched files on one named server still match.
get_capacity_trends
Where disk and memory are heading on a server.
list_alerts
Alerts already raised across the workspace.
backup_status
Every backup destination on this machine, and how each is doing.

What an agent never receives

Escalation shells — sudo -i, su, sudo bash — are refused for every access group, with no setting that turns them back on. Output is scanned for secrets and secret-shaped strings before it is returned. Every action, allowed or refused, lands in the audit log.

Read the threat model

Connecting a client

The bridge listens on 127.0.0.1 and is off until you turn it on under AI & MCP. Everything below assumes OpsMaxx is running.

Claude Code

One command. A pairing code appears in the app, so there is no token to copy.

opsmaxx claude

Codex

The same pairing flow, writing a managed block into ~/.codex/config.toml.

opsmaxx codex

Claude Desktop

Desktop cannot express an HTTP MCP server with a header, so it needs the stdio bridge. Drop the env block entirely if you have run opsmaxx claude once.

{
  "mcpServers": {
    "opsmaxx": {
      "command": "npx",
      "args": ["-y", "@opsmaxx/mcp"],
      "env": {
        "OPSMAXX_MCP_TOKEN": "<token>",
        "OPSMAXX_MCP_PORT": "<port>"
      }
    }
  }
}

Any other MCP client

Streamable HTTP with a bearer token, generated under AI & MCP → Security.

{
  "mcpServers": {
    "opsmaxx": {
      "type": "http",
      "url": "http://127.0.0.1:<port>/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}