Appearance
MCP tools
The tools Pomelo's MCP server gives a coding agent working in a workspace. The app registers the server with Claude Code in ~/.claude.json (see Settings > Agent > MCP Server); any other MCP client can run pom mcp [--branch <branch>] over stdio. The project is the pom.yml above the directory the server starts in; the workspace is --branch, else the workspace--<branch> folder it starts in, else main.
A read-only tool changes nothing. A result longer than the limit shown is cut, and the full text is saved to a file under ~/.local/state/pom/mcp-out/ whose path ends the result.
workspace_info
Overview of THIS workspace: branch, repos, and their services (running state, ports, modes, agent state), plus the shared services (Docker image or cmd process) with state, port and url.
Read-only.
services
List this workspace's services with running state and allocated port, then the shared services every workspace uses (Repo "shared", Kind image or cmd, Url).
Read-only.
ports
Map of this workspace's services to their allocated localhost ports.
Read-only.
service_url
The base URL to reach a service (dev-proxy domain if configured, else http://localhost:<port>). Curl it via run_in_env, e.g. curl -s $(url)/health.
Read-only.
| Argument | Type | Required | Description |
|---|---|---|---|
repo | string | no | repo name/alias; omit for workspace-level services (Claude Code, editor) |
service | string | yes | service name |
databases
This branch's databases with ready-to-use Postgres connection strings. Use these to run migrations/queries against the per-branch DB.
Read-only.
db_list
List the databases you can browse in THIS branch, each with name (use it as db in db_tables/db_columns/db_query), engine (postgres|redis), repo, and label. Includes shared Redis keyspaces. Prefer this + db_query to inspect data over spinning up psql via run_in_env.
Read-only.
db_tables
List a database's tables/views (postgres) or keyspaces (redis). db is a name from db_list.
Read-only.
| Argument | Type | Required | Description |
|---|---|---|---|
db | string | yes | database name from db_list |
db_columns
List every column (schema/table/name/type) in a database - use to learn the schema before writing a query. db is a name from db_list.
Read-only.
| Argument | Type | Required | Description |
|---|---|---|---|
db | string | yes | database name from db_list |
db_query
Run SQL against a branch database (postgres) or a command against Redis, returning columns + rows. db is a name from db_list. Reads are safe; writes hit the REAL per-branch DB - verify with a SELECT first. Results are capped by limit (default 200).
Not read-only; results over 12000 characters are cut.
| Argument | Type | Required | Description |
|---|---|---|---|
db | string | yes | database name from db_list |
limit | integer | no | max rows (default 200) |
sql | string | yes | SQL (postgres) or a Redis command (e.g. GET key) |
db_snapshots
List THIS workspace's database snapshots: each name with its databases, sizes and when it was taken, plus the total size. ws__baseline is the state right after the workspace was created; take others with db_snapshot.
Read-only.
db_snapshot
Save every database of THIS workspace as snapshot name (letters, digits, - and _), so db_restore can put exactly this data back later - e.g. before a test that writes. Briefly disconnects the workspace's own services from their databases. Refused if the name exists unless replace is true. Never touches main or other workspaces.
Not read-only.
| Argument | Type | Required | Description |
|---|---|---|---|
name | string | yes | snapshot name, e.g. before-checkout |
replace | boolean | no | take it again if it exists (default false) |
db_restore
Put snapshot name back into every database of THIS workspace (see db_snapshots). STOPS the workspace's running services, replaces each database with its snapshot copy, then STARTS them again. Every change since the snapshot is lost. Refused on main.
Not read-only; destructive.
| Argument | Type | Required | Description |
|---|---|---|---|
name | string | yes | a snapshot from db_snapshots |
db_baseline
Run THIS workspace's migrations, then save its databases again as ws__baseline - after a migration changes the schema, so later resets start from the migrated data. Refused on main.
Not read-only.
db_reseed
Replace THIS workspace's data: from main's main__baseline (default, without disconnecting main) or from one of its own snapshots (snapshot). Then runs its migrations and saves ws__baseline again. STOPS and restarts the workspace's running services. Refused on main.
Not read-only; destructive.
| Argument | Type | Required | Description |
|---|---|---|---|
snapshot | string | no | one of this workspace's snapshots instead of main__baseline |
service_start
start a service in this workspace and report status. Ports are pre-flighted, so a started service is guaranteed to bind the port pom reports.
Not read-only.
| Argument | Type | Required | Description |
|---|---|---|---|
repo | string | no | repo name/alias; omit for workspace-level services (Claude Code, editor) |
service | string | yes | service name |
service_stop
stop a service in this workspace and report status. Ports are pre-flighted, so a started service is guaranteed to bind the port pom reports.
Not read-only.
| Argument | Type | Required | Description |
|---|---|---|---|
repo | string | no | repo name/alias; omit for workspace-level services (Claude Code, editor) |
service | string | yes | service name |
service_restart
restart a service in this workspace and report status. Ports are pre-flighted, so a started service is guaranteed to bind the port pom reports.
Not read-only.
| Argument | Type | Required | Description |
|---|---|---|---|
repo | string | no | repo name/alias; omit for workspace-level services (Claude Code, editor) |
service | string | yes | service name |
shared_start
Start a shared service (one Docker container or one cmd process for every workspace of the project). A no-op when it already runs.
Not read-only.
| Argument | Type | Required | Description |
|---|---|---|---|
force | boolean | no | stop/restart even while other workspaces run services |
name | string | yes | shared service name (a key of shared_services) |
shared_stop
Stop a shared service for EVERY workspace. Refused while other workspaces run services, unless force: true.
Not read-only.
| Argument | Type | Required | Description |
|---|---|---|---|
force | boolean | no | stop/restart even while other workspaces run services |
name | string | yes | shared service name (a key of shared_services) |
shared_restart
Restart a shared service for every workspace (e.g. after editing its cmd or environment). Refused while other workspaces run services, unless force: true.
Not read-only.
| Argument | Type | Required | Description |
|---|---|---|---|
force | boolean | no | stop/restart even while other workspaces run services |
name | string | yes | shared service name (a key of shared_services) |
commands
The project's PRE-WRITTEN commands per repo: one-time setup steps and shortcuts (each with key->desc->cmd), already preset-resolved. ALWAYS check here before hand-writing a shell command - these carry the project's canonical install / generate / migrate / lint / test / build invocations (e.g. npx prisma generate, bundle exec rake db:migrate). Run one with run_shortcut (by key when present, else desc) or, for a raw setup step, run_in_env.
Read-only.
run_shortcut
Run one of a repo's PRE-WRITTEN shortcuts, in the repo's worktree with the workspace's resolved env. Address it by key (the canonical op - install/generate/migrate/test/lint/build/format; see each shortcut's key in commands) OR by desc. PREFER key when it exists - it's stable across projects. PREFER this over run_in_env whenever a shortcut exists - it uses the project's exact, tested command. Synchronous.
Not read-only; results over 8000 characters are cut.
| Argument | Type | Required | Description |
|---|---|---|---|
desc | string | no | the shortcut's description, or a unique substring of it (use when there's no key) |
key | string | no | canonical op: install/generate/migrate/test/lint/build/format |
repo | string | yes | repo name/alias |
service_logs
Recent terminal output of a service (to check for errors like a port-in-use).
Read-only; results over 8000 characters are cut.
| Argument | Type | Required | Description |
|---|---|---|---|
lines | integer | no | how many trailing lines (default 200) |
repo | string | no | - |
service | string | yes | - |
run_in_env
Run a shell command in a repo's worktree with the workspace's resolved env (correct DATABASE_URL/ports). Use to run migrations, tests, seeds and verify against the REAL running stack. Synchronous, 5-min timeout. NOTE: if the project already defines a setup step or shortcut for this task (call commands to check), prefer run_shortcut so you use the project's canonical invocation instead of guessing one.
Not read-only; results over 8000 characters are cut.
| Argument | Type | Required | Description |
|---|---|---|---|
cmd | string | yes | shell command |
repo | string | yes | repo name/alias to run in |
resolve_port_conflict
Move this workspace to a fresh, fully-free port region and regenerate its env - the self-heal when a service can't bind because something grabbed pom's port. Running services restart on their new ports.
Not read-only.
config_get
Read this project's pom.yml (services, repos, shared services - Docker image or cmd -, env profiles, databases). What each key means: config_reference.
Read-only.
config_reference
The pom.yml reference: every key the config reads (type, default, what it does, examples), every {{...}} template token, and the removed keys and colon forms with their replacements. Read it before writing a config with config_set.
Read-only.
secrets_list
List the NAMES of secrets in the app-local secret store (values are never returned). Onboarding imports a project's gitignored .env values here - wire each into the config env as {{secret.NAME}} (a real secret) or map infra to {{shared.*}} instead.
Read-only.
config_validate
Dry-run validate a proposed pom.yml (schema + reference checks) WITHOUT writing. Always validate before config_set. Every key and token: config_reference. A shared service is either a Docker image: or a cmd: run once for every workspace, e.g. shared_services: {mock-as: {cmd: node scripts/mock-as.js, repo: api, port: 4010}} (repo: run in that repo's main checkout; port: else one is leased and given as $PORT); reach it with {{shared.mock-as.url}}.
Read-only.
| Argument | Type | Required | Description |
|---|---|---|---|
yaml | string | yes | - |
config_set
Validate and write a new pom.yml, then reload - adds/edits services, repos, shared services, databases, env. Rejected if invalid (nothing is written). Newly added services get ports allocated automatically. A shared service is a Docker image: or a cmd: (one process for every workspace, optional repo/port/environment/healthcheck); start it with shared_start. Every key and token: config_reference.
Not read-only.
| Argument | Type | Required | Description |
|---|---|---|---|
yaml | string | yes | - |
config_doctor
Diagnose whether this project is runnable: returns structured findings (invalid config, missing docker/tools, missing repos, unset {{secret}}). Use this to drive a fix loop - after each config edit, call config_doctor again until it reports no errors.
Read-only.
config_normalize
Deterministically clean the config: strip REMOVED schema keys (schema_version/plugins/combinations/proxy/webhook/exposes), and migrate legacy colon tokens to dot form. Run this as the FINAL step of Adapt/onboarding - it does the mechanical cleanup so you don't have to.
Not read-only.
agent_list
The coding-agent sessions of THIS workspace: role, state (idle, thinking, tool_use, awaiting_input, died), turn, and whether you may drive it. Only this workspace's sessions exist for you.
Read-only.
agent_start
Start another agent session in THIS workspace on a fresh conversation of its own (for example a reviewer that must not share your context). You hold its lease: you may send it turns.
Not read-only.
| Argument | Type | Required | Description |
|---|---|---|---|
allowed_tools | array | no | - |
disallowed_tools | array | no | - |
model | string | no | - |
prompt | string | no | Its first turn. |
role | string | yes | A new role for the session, like reviewer (lowercase letters, digits, dashes). |
system_prompt | string | no | - |
tools | string | no | The tool set it has, like Read,Grep,Glob. |
agent_send
Send one turn to another agent session of THIS workspace and return its turn number. Refused if it is busy, if a person drives it, if you are sending too fast (once per 5 s, 20 per hour), or if agents are already two deep. Use agent_wait and agent_read for the result, or agent_ask for all three.
Not read-only.
| Argument | Type | Required | Description |
|---|---|---|---|
role | string | yes | The session's role in this workspace, from agent_list (claude, reviewer, fixer...). |
text | string | yes | - |
agent_wait
Wait for another agent session of THIS workspace: until its turn ends (default), it is idle, or it asks for a permission. Returns reached (turn-end, idle, awaiting_input, timeout, died) and the stop reason.
Read-only.
| Argument | Type | Required | Description |
|---|---|---|---|
role | string | yes | The session's role in this workspace, from agent_list (claude, reviewer, fixer...). |
timeout_s | integer | no | At most 600; wait again to keep waiting. |
turn | integer | no | - |
until | string | no | - |
agent_read
What another agent session of THIS workspace did in a turn: its prompt, text, tool calls with results, stop reason and token usage, read from its transcript.
Read-only.
| Argument | Type | Required | Description |
|---|---|---|---|
full | boolean | no | Tool results in full instead of cut at 2 KB. |
role | string | yes | The session's role in this workspace, from agent_list (claude, reviewer, fixer...). |
since | integer | no | - |
turn | integer | no | One turn; the last by default. |
agent_ask
Ask another agent session of THIS workspace one question and get its answer: sends a turn, waits for it to end, and returns what it did. The same limits as agent_send apply.
Not read-only.
| Argument | Type | Required | Description |
|---|---|---|---|
role | string | yes | The session's role in this workspace, from agent_list (claude, reviewer, fixer...). |
text | string | yes | - |
timeout_s | integer | no | At most 600. |
agent_approve
Answer a pending approval of another agent session of THIS workspace, once (approve or deny). Use it only for a call you would make yourself.
Not read-only.
| Argument | Type | Required | Description |
|---|---|---|---|
deny | boolean | no | - |
request | string | yes | The id from its permission_request (pending approval <id>). |
role | string | yes | The session's role in this workspace, from agent_list (claude, reviewer, fixer...). |