MCP Overview
How Piyaz exposes its tools via the Model Context Protocol.
Piyaz ships an MCP server that gives any compatible client (Claude Code, Codex, Cursor, Antigravity, or any other MCP client) direct access to your project graph. The server exposes 9 tools over an HTTP endpoint and embeds instructions that teach the agent the complete Piyaz workflow, from planning through execution and tracking.
No manual prompting required. On connect, the client learns how to navigate tasks, claim work, pull context, and record results. This page is the map of that surface for humans; the agent already receives the operating instructions on connect.
Ref-first and stateless
Two properties shape how the tools compose:
- Refs are first-class. A task ref (
PYZ-42) or project ref (PYZ) names a task or project anywhere. The server resolves refs on the fly, org-bounded: an ambiguous ref returns a candidate list, a near-miss the closest existing ref. Responses emit refs, so the result of one step names the input to the next. - The server is stateless. There is no "active" project or server-side session. Each step names the project or task it acts on. Starting a session is just discovering which refs exist.
Architecture
The MCP server is a hosted HTTP endpoint at https://app.piyaz.ai/api/mcp. Your client connects over HTTP and authenticates with OAuth on the first tool call. The server reads and writes the same Postgres-backed graph as the web UI.
┌─────────────┐ HTTP + OAuth ┌──────────────────────┐ SQL ┌────────────┐
│ MCP Client │ ───────────────── │ Piyaz MCP endpoint │ ────────── │ PostgreSQL │
│ (Claude Code,│ JSON-RPC │ app.piyaz.ai/api/mcp│ │ │
│ Codex, ...) │ ◄─────────────── │ │ ◄────────── │ │
└─────────────┘ └──────────────────────┘ └────────────┘The plugins ship one MCP server, piyaz, pointing at the hosted endpoint. If you self-host, run the server yourself and register a second MCP server in your editor that points at it. See the self-host guide for the setup.
The nine tools
Each tool maps to a stage of the brainstorm > decompose > manage workflow. Follow a tool's link for its full parameter tables.
| Tool | Stage | Purpose |
|---|---|---|
piyaz_workspace | Session start / setup | Identify the caller; list teams and projects; create and update projects; manage the category vocabulary |
piyaz_search | All | Find tasks across projects by text, status, priority, assignee, category, or tags |
piyaz_get | All | Read one task through one of six lenses, or one project (meta or overview) |
piyaz_create | Decompose | Create up to 25 tasks and the edges between them in one atomic, idempotent call |
piyaz_edit | Manage | Apply an ordered list of operations to one task, atomically |
piyaz_link | Decompose / Manage | Create, update, or remove dependency edges |
piyaz_map | Manage | Navigate the graph: ready, blocked, plannable, critical path, downstream, neighbors |
piyaz_activity | Resume | See what changed, newest first, since a given moment |
piyaz_note | Knowledge | Create, read, edit, and organize project notes; the shared knowledge base agents read and write, with guidance notes auto-injected into task context |
The workflow the server teaches
On connect, Piyaz sends embedded instructions that define how the agent operates. Claude auto-loads them; other clients surface them as system context. They encode one continuous loop, and you never have to recite it:
- Start the session. The agent confirms who you are and lists every project it can reach, so the rest of the session can name projects by ref.
- Find work. It leads with the graph: the critical path on resume, the ready set for what is actionable now, the plannable set when nothing is ready to code, the blocked set to diagnose a stall. Free-text and filtered lookups fall back to search.
- Read the right amount. It pulls a task through the lightest lens that answers the question, and reads a project's vocabulary or full overview when it needs the wider picture.
- Plan, then implement. It writes an implementation plan into the task, claims the task, pulls the full agent context, does the work, and records the outcome in one atomic write: execution record, decisions, files, evaluated acceptance criteria, and the PR link.
- Wire and propagate. New tasks and their dependency edges are created together; after any change, the agent checks downstream tasks and keeps edge notes and descriptions current.
- Resume cleanly. Returning after a break, it reads what changed while it was away and re-reads only the tasks that moved.
An agent's terminal write is in_review, never done. It records what it built and hands off; a human flips in_review → done after approving the PR (or Composer does, under a merge policy you set). Skipping the execution record breaks the context chain. Downstream tasks depend on knowing what was built, what was decided, and which files changed.
Hints and errors
Tool responses may carry a _hints field with contextual guidance: a missing field, a suggested next step, a lifecycle transition to run. Errors carry their fix inline: candidate refs for an ambiguous name, the closest ref on a near-miss, the current item ids for a missed target, the fresh timestamp on a stale write. These reflect server-side state the agent cannot otherwise see, so they override its prior plan, and it acts on them before asking you.
Connect your client
Claude Code
Plugin marketplace install: tools, skills, and agents.
Codex
Plugin install over the hosted MCP endpoint.
Cursor
MCP deeplink quick-start, or the Team marketplace for skills.
Antigravity
MCP server config plus the bundled workflow plugin.
Last updated