MCP Overview

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 6 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.

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, ...) │ ◄─────────────── │                      │ ◄────────── │            │
└─────────────┘                   └──────────────────────┘            └────────────┘

If you self-host, run the server yourself and point your client at the piyaz-local server, which targets http://localhost:3000/api/mcp. See the self-host guide for the setup.

Tools

Six tools, each mapping to a phase of the brainstorm > decompose > manage workflow:

Each tool above links to its full parameter tables and per-action examples.

Server Instructions

On connect, Piyaz sends embedded instructions that define how the AI should operate. Claude auto-loads these; other clients surface them as system context.

The instructions encode a continuous loop: start session > find work > implement > record.

Session Start

piyaz_project action='list'   → pick a project
piyaz_project action='select' → set it as current
piyaz_query   type='overview' → see all tasks, progress, dependencies

Find Work

Implement a Task

1. Claim: piyaz_task action='update' status='in_progress' -- prevents double-assignment.
2. Get context: piyaz_context depth='agent' -- multi-hop dependencies + execution records from upstream tasks.
3. Do the work.
4. Record: piyaz_task action='update' status='done' with all of:
   • executionRecord -- 3-5 sentences on what was built (function names, file paths, endpoints).
   • decisions -- one-liner per technical choice (what + why).
   • files -- every file created or modified.

Plan a Draft Task

1. piyaz_context depth='planning' -- returns spec, prerequisites, and related work.
2. Write a detailed plan: file paths, line numbers, specific changes, verification steps.
3. piyaz_task action='update' implementationPlan='...' status='planned'

Create a Task

1. piyaz_task action='create' with title (verb + noun), description, acceptance criteria, tags.
2. piyaz_edge action='create' to wire it into the dependency graph.
3. piyaz_query type='edges' to verify edges look correct.

Edges

Edges make Piyaz a context network. They drive ready/blocked analysis, critical path computation, and context propagation between tasks.

• depends_on -- source cannot start until target is done. Use when removing the target makes the source impossible.
• relates_to -- shared context, no blocking. Use when removing the target just makes the source harder.

Always include a note explaining why the relationship exists. Notes propagate into downstream agent context.

Hints

Tool responses may include a _hints field with contextual guidance -- missing fields, suggested next steps, or warnings. These are generated dynamically based on the current state of your data. Follow them.

Connect Your Client