MCP tools
The eleven tools Claude Code and Codex use to change the backend.
npx shipmantis mcp serves the Mantis tools over stdio. init registers it for both agents, so
after a restart they see a server called mantis:
{
"mcpServers": {
"mantis": {
"command": "npx",
"args": ["-y", "shipmantis", "mcp"]
}
}
}The server reads MANTIS_URL, MANTIS_SECRET_KEY and MANTIS_BRANCH from .env.local, then
.env, in the folder the agent runs in. It holds the secret key, so the agent's queries skip the
access rules, but a change on main that can lose data or let more people in still
waits for a person.
Schema
| Tool | Arguments | What it does |
|---|---|---|
read_schema | branch | The branch's current schema and version. |
plan_migration | schemaPath, branch | Plans the schema file against the branch without changing anything. Each step is marked safe or destructive, with its SQL. |
apply_migration | schemaPath, branch | Applies the schema file. On main a destructive step holds the whole change and the answer carries the change's id instead of a version. |
undo_migration | branch | Undoes the latest migration, bringing dropped tables and columns back with their data. Held on main if it can lose data. |
check_change | id | Whether a held change is pending, approved, rejected or stale. |
schemaPath is relative to the project and defaults to mantis/schema.ts.
Branches
| Tool | Arguments | What it does |
|---|---|---|
list_branches | Every branch and the one it came from. | |
create_branch | name, from | A full copy of from (default main), schema and data. |
promote_branch | name | Applies the branch's schema to its parent. Data is not copied. Held on main if destructive. |
Rewind
| Tool | Arguments | What it does |
|---|---|---|
preview_rewind | to, table, id, branch | What rewinding to to would undo, without changing anything. |
rewind | to, table, id, branch | Undoes every write since to. Held on main. |
to is a time with an offset, like 2026-10-14T09:30:00Z, or 30m, 2h, 1d ago. id needs
table.
Data
| Tool | Arguments | What it does |
|---|---|---|
run_query | query, branch | Runs one query with the secret key. |
query is the same shape the client sends:
{ "op": "select", "table": "todos", "where": { "done": false }, "orderBy": [{ "column": "createdAt", "direction": "desc" }], "limit": 20 }
{ "op": "insert", "table": "todos", "rows": [{ "title": "a" }] }
{ "op": "update", "table": "todos", "set": { "done": true }, "where": { "id": "…" } }
{ "op": "delete", "table": "todos", "where": { "done": true } }How the agent is told to work
init also writes .claude/skills/mantis/SKILL.md and a section of AGENTS.md that tell the
agent to read the schema first, plan before applying, try risky changes on a branch, treat a held
change as waiting rather than failed, and never print or commit the secret key. Running init
again rewrites SKILL.md and the part of AGENTS.md between <!-- mantis:start --> and
<!-- mantis:end -->, so put your own instructions outside them.