Claude Code

Wire Claude Code to agentry so Claude can create sandboxes, write files, run commands, and ship apps on your server.

You'll need

• The agentry CLI installed and signed in. See Quick start, step 1–2.
• Claude Code installed locally.
• ~3 minutes.

Add agentry as an MCP server

In a terminal:

claude mcp add agentry -- agentry mcp

That's it. Claude Code rewrites its config and reloads MCP servers on next launch.

What this command does

• Registers a new MCP server named agentry.
• Tells Claude to launch it via agentry mcp — the agentry CLI's MCP transport.
• The mcp subcommand opens a long-lived MCP session against the agentry control plane, scoped to your signed-in account.

Restart Claude Code

Quit and relaunch the app. (On macOS: Cmd-Q. Tray icon close isn't enough — the MCP host runs in the main process.)

Verify

Open a new conversation in Claude Code and type:

List the agentry tools you have.

You should see Claude list tools like sandbox_create, sandbox_list, app_probe, command_run, file_write, file_read, file_list, port_wait, project_start, and friends. If those appear, you're wired.

If they don't, see MCP wiring troubleshooting.

Try it

Prompt:

Use agentry to build a hello-world homepage — a single page that says "Hello from agentry". Start the dev server.

Claude should call sandbox_create, scaffold the page, start the dev server, and tell you the port it's listening on. It won't hand you a public link — sandboxes don't publish ports until you ask. To see the page, open the sandbox in the dashboard and click Share for a *.agentry.live preview URL (see Preview what was built).

You're done. Claude can now build, run, and ship on your server.

Manual configuration (alternative)

If claude mcp add doesn't work for you, edit the config file by hand.

Open ~/.claude.json (the file claude mcp add writes — see the Claude Code docs for project- vs user-scoped config). Add an entry under mcpServers:

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

Save, restart Claude.

If agentry isn't on the path Claude searches, use the full path:

{
  "mcpServers": {
    "agentry": {
      "command": "/Users/you/.local/bin/agentry",
      "args": ["mcp"]
    }
  }
}

Find the full path with which agentry.

Pin a specific server

By default, agentry uses whichever server you set as the current server (via agentry server use). If you want this Claude session pinned to one server even when your current changes:

claude mcp add agentry -- agentry mcp --server <server-name>

Or in the JSON:

{
  "mcpServers": {
    "agentry": {
      "command": "agentry",
      "args": ["mcp", "--server", "homelab"]
    }
  }
}

Useful when you have a prototyping laptop and a production box — wire each to its own Claude profile.

Common gotchas

Claude lists 0 agentry tools

You probably hit one of these:

• agentry CLI not on $PATH Claude can see. Use the full path in the JSON.
• The CLI isn't signed in. Run agentry login from a terminal first.
• An old MCP session is cached. Quit Claude completely (Cmd-Q), then relaunch.

If the tool list still doesn't show up, see MCP wiring troubleshooting.

"no server set" error

You connected your machine as a server, but didn't pick one as current. Run agentry server use <server-name> (the name from agentry server ls), then restart Claude.

Switch between models with OpenRouter

If you want to try Claude, GPT, Gemini, or open-weights models without re-keying your setup, point Claude Code at OpenRouter as its model provider.

OpenRouter exposes a single OpenAI-compatible API endpoint that fronts ~200 models. One key, one bill, every model. Most harnesses (Claude Code included) accept it as a drop-in OpenAI replacement.

Set the OpenRouter base URL + key in Claude Code's model settings, then use model strings like anthropic/claude-3.5-sonnet, openai/gpt-4o, google/gemini-2.0-flash, or meta-llama/llama-3.3-70b-instruct. Switch models by changing one string; agentry doesn't care which one you pick.

This is the cleanest fit for the "your model, your key, your rate" pitch — see concepts.

What Claude can do now

Read the MCP tools reference for the full list. Highlights:

• sandbox_create — spin up a new sandbox on your server
• app_probe — check the running app actually responds (use this before saying "done")
• command_run — run a shell command in a sandbox
• file_write, file_read, file_list, file_grep — work the filesystem
• port_wait — wait for the dev server to come up
• project_start, project_list, project_logs — manage long-running processes

For how to phrase requests so Claude uses these well, see the prompting guide.

Next

• Prompting that works — patterns and gotchas.
• Ship an app — the deploy flow.
• Add a database — bind Mongo or Postgres so every app you build inherits the connection.