Skip to content
PtahPtah
Edit this pagePropose a change on GitHubView sourceOpen the source used for this buildReport a documentation issueOpen a prefilled GitHub issue

AI and agents overview

Ptah exposes its schema and migration operations to a model without granting a general shell or unrestricted filesystem access. Choose who drives the session:

Situation Use Who owns the model connection
Ask Ptah a question or hold a Ptah-focused conversation ptah assist Ptah calls the provider profile you configure.
Add Ptah tools to Claude, Cursor, VS Code, Zed, or another MCP client ptah mcp The client starts Ptah and chooses the model.

Both surfaces use the same Ptah tool and capability model. Neither grants a model permission to apply migrations to a database. A client may provide its own shell, filesystem, or network tools; Ptah cannot constrain tools it does not serve.

Start with no authority

Section titled “Start with no authority”

A bare ptah mcp process serves reading tools but has no schema root, database, or workspace to reach. You add each scope explicitly:

Terminal window
ptah mcp --schema-source-root ./models

Adding a workspace exposes artifact read and preview tools. It still does not permit writes:

Terminal window
ptah mcp \
  --workspace . \
  --migrations-dir ./migrations \
  --dialect postgres

Connect an MCP client gives the client-specific configuration. Agent permissions explains schema, database, and artifact authority before you widen it.

A change is always previewed

Section titled “A change is always previewed”

Ptah artifact changes follow one sequence:

read current digest -> preview a patch -> approve when required -> apply -> verify or undo

The preview writes nothing. Its token is single-use, expires after fifteen minutes, and belongs to one content-addressed patch. Apply checks that the artifact still has the digest the preview saw. It recomputes migration integrity, runs artifact-specific gates, and undoes a patch that introduces an error.

Review and apply an agent patch walks through that sequence. MCP tool reference lists every tool and argument without mixing the lookup material into the workflow.

Decide what to trust

Section titled “Decide what to trust”

Ptah constrains Ptah operations, not the model. The useful controls are:

  • configured roots and directories bound when the server starts;
  • explicit database identity and class, never a database URL supplied by the model;
  • capability verdicts of allow, ask, or deny;
  • repository policy that can only remove authority;
  • artifact digests, single-use previews, verification gates, and rollback;
  • an audit record containing permissions, refusals, paths, digests, and gates.

Repository text is returned as data, not instructions, but labels are not a security boundary. Capability checks, path containment, and verification gates are the controls.

Common next tasks

Section titled “Common next tasks”