Agent Setup

OpenIslands is built for an AI agent to own a dashboard. Any agent that speaks the Model Context Protocol can drive it — this page covers connecting four of them: Hermes, OpenClaw, Claude Code, and Codex CLI.

What's common to all of them

Every agent drives the same MCP edit loop. OpenIslands ships a standard stdio MCP server, @openislands/mcp, and init scaffolds everything an agent needs to find it:

• a .mcp.json wiring the server (pointed at the project root that holds app/manifest.json),
• an AGENTS.md pointing the agent at the conventions,
• the OpenIslands skill under .agents/skills/openislands/.

So the agent reads the live contract, stages a validated patch_manifest / propose_edit, applies it, and can roll it back — the tools and guarantees are identical whichever agent you use. See the MCP Server page for the full tool list and the read-many/write-one model; this page only covers the per-agent wiring.

The server invocation is always the same — npx -y @openislands/mcp <project-root> over stdio — so if an agent isn't listed below, point its MCP config at that command and drop an AGENTS.md (or its own project-instructions file) at the project root.

{
  "mcpServers": {
    "openislands": {
      "command": "npx",
      "args": ["-y", "@openislands/mcp", "."]
    }
  }
}

Hermes

Hermes is Nous Research's self-hosted autonomous agent — it runs on your own hardware, writes and runs code, and calls external tools over MCP.

Wire up the server. Hermes reads its config from ~/.hermes/config.yaml, under an mcp_servers map (or run hermes mcp add openislands to add it interactively):

mcp_servers:
  openislands:
    command: npx
    args: ["-y", "@openislands/mcp", "/path/to/your/project"]

Project guidance. Hermes loads an AGENTS.md from the working directory into its system prompt at session start — the one init already wrote. Point it at your project directory and it picks up the conventions; the skill under .agents/skills/ documents the full edit loop.

Tips.

• Hermes is a long-running autonomous agent, so lean on the safety boundary: every manifest change is staged, diffed, and reversible. Let it propose and apply through the MCP rather than touching files directly.
• Since it self-hosts, the npx invocation needs Node ≥ 20 available in the environment Hermes runs in.

OpenClaw

OpenClaw is an open-source personal agent that runs anywhere and connects to external tools over MCP (it integrates mcporter).

Wire up the server. OpenClaw reads ~/.openclaw/openclaw.json. Note its MCP servers live under a nested mcp.servers key (not Claude Code's top-level mcpServers):

{
  "mcp": {
    "servers": {
      "openislands": {
        "command": "npx",
        "args": ["-y", "@openislands/mcp", "/path/to/your/project"]
      }
    }
  }
}

Or add it from the CLI with openclaw mcp add (check openclaw mcp --help for the current flag spelling), then openclaw mcp doctor openislands to confirm it launches.

Project guidance. OpenClaw reads AGENTS.md as its project rules — the same file init drops. It also honors a sibling CLAUDE.md, so the convention of symlinking CLAUDE.md → AGENTS.md keeps one source of truth.

Tips.

• Mind the nesting: mcp.servers, not mcpServers. It's the easiest thing to get wrong moving a config over from Claude Code.
• Confirm the connection with openclaw mcp doctor before driving it — a misnested key fails silently otherwise.

Claude Code

Claude Code is Anthropic's agentic coding CLI, and the default OpenIslands target — init's scaffold is already shaped for it.

Wire up the server. Claude Code reads project-scoped MCP servers from .mcp.json at the project root — exactly the file init writes, so there's nothing to do:

{
  "mcpServers": {
    "openislands": {
      "command": "npx",
      "args": ["-y", "@openislands/mcp", "."]
    }
  }
}

To add it by hand, claude mcp add --transport stdio openislands --scope project -- npx -y @openislands/mcp . writes the same project-scoped entry. (Claude Code prompts to approve a project .mcp.json server on first use.)

Project guidance. Claude Code reads CLAUDE.md as project memory and discovers skills under .agents/skills/. The scaffold ships the OpenIslands skill, so it loads automatically whenever you edit a project that has an app/manifest.json. (AGENTS.md is conventionally symlinked to CLAUDE.md.)

Tips.

• Just open the scaffolded folder — project-scoped .mcp.json and the skill are picked up with no manual MCP setup.
• The skill's edit loop is the contract: prefer patch_manifest, pass JSON objects, and never work around a binding error.

Codex CLI

Codex CLI is OpenAI's coding agent CLI. It reads AGENTS.md natively, so the scaffold's conventions apply out of the box.

Wire up the server. Codex configures MCP servers in ~/.codex/config.toml, as [mcp_servers.<name>] TOML tables:

[mcp_servers.openislands]
command = "npx"
args = ["-y", "@openislands/mcp", "/path/to/your/project"]

Or add it from the CLI: codex mcp add openislands -- npx -y @openislands/mcp /path/to/your/project. (Environment variables go in a [mcp_servers.openislands.env] sub-table — not the unrelated env_vars allowlist key.)

Project guidance. Codex reads AGENTS.md — the file init writes. It merges AGENTS.md files from your home directory down to the working directory, concatenated root-to-cwd with the closest-to-cwd file taking precedence, so the project's AGENTS.md lands on top.

Tips.

• Codex's MCP config is global (~/.codex/config.toml), not per-project, so pass an absolute project path in args rather than ..
• The project AGENTS.md points at the skill under .agents/skills/openislands/ — read it for the full edit loop and CRUD recipes.

Where to go next

• MCP Server — the full tool set and the read-many/write-one safety model every agent shares.
• Getting Started — scaffold a project and drive your first edit.
• The Manifest — what every edit validates against.