MCP Server¶

Pisama exposes its detection, scoring, and healing capabilities as MCP (Model Context Protocol) tools. Any MCP-compatible coding agent — Claude Code, Cursor, Gemini CLI, Windsurf, Android Studio Agent Mode — can call them directly from chat.

Overview¶

The server bridges the agent IDE and the Pisama backend over stdio (the default MCP transport). All 12 tools call the Pisama REST API and return structured JSON that the calling LLM can act on.

IDE → stdio → pisama-mcp-server → HTTPS → api.pisama.ai

Prerequisites¶

Python 3.11+
Pisama backend running (cloud at api.pisama.ai or self-hosted)
API key and tenant ID — generate one at pisama.ai/settings/api-keys

Installation¶

The MCP server ships inside the Pisama backend package. From your cloned repo:

cd ~/pisama/backend
pip install -e ".[mcp]"   # installs mcp[cli] + httpx dependencies

Verify it starts:

python -m app.mcp.server \
  --base-url https://api.pisama.ai \
  --api-key  pisama_... \
  --tenant-id 679994b8-...

You should see no output (server is waiting on stdin). Ctrl-C to exit.

Configure in Claude Code¶

Add to ~/.claude/settings.json (or the project .claude/settings.json):

{
  "mcpServers": {
    "pisama": {
      "command": "python",
      "args": [
        "-m", "app.mcp.server",
        "--base-url",  "https://api.pisama.ai",
        "--api-key",   "pisama_YOUR_KEY",
        "--tenant-id", "YOUR_TENANT_UUID"
      ],
      "cwd": "/path/to/pisama/backend"
    }
  }
}

Reload Claude Code. Type /mcp to confirm pisama appears connected.

Configure in Cursor / Windsurf¶

In .cursor/mcp.json (or the IDE equivalent):

{
  "mcpServers": {
    "pisama": {
      "command": "python",
      "args": [
        "-m", "app.mcp.server",
        "--base-url",  "https://api.pisama.ai",
        "--api-key",   "pisama_YOUR_KEY",
        "--tenant-id", "YOUR_TENANT_UUID"
      ],
      "cwd": "/path/to/pisama/backend"
    }
  }
}

Tool Reference¶

All tools accept and return JSON. Error responses set isError: true and include a structured { "error": { "code": "...", "message": "...", "detail": ... } } payload.

Observation¶

Tool	Description	Required args
`pisama_query_traces`	Paginated trace search — framework, status, date filters	none
`pisama_get_trace_detail`	Full trace: all agent states, detections, timeline	`trace_id`
`pisama_query_detections`	Paginated detection search — type, confidence, trace filters	none
`pisama_get_detection_detail`	Detection detail: explanation, evidence, confidence breakdown, fixes	`detection_id`

Remediation¶

Tool	Description	Required args
`pisama_get_fix_suggestions`	Fix suggestions for a detection (type, risk, confidence)	`detection_id`
`pisama_apply_fix`	Apply a suggested fix to the runtime/config	`detection_id`, `fix_id`
`pisama_generate_source_fix`	Generate a source code patch to fix a detection's root cause	`detection_id`, `file_path`, `file_content`, `language`

Evaluation¶

Tool	Description	Required args
`pisama_submit_feedback`	Mark a detection as true/false positive	`detection_id`, `is_correct`
`pisama_create_scorer`	Create a custom LLM-backed scorer from a description	`name`, `description`
`pisama_list_scorers`	List custom scorers for this tenant	none
`pisama_run_scorer`	Run a scorer against recent traces	`scorer_id`
`pisama_evaluate_conversation`	Run the full conversation quality evaluation on a trace	`trace_id`

Key parameter notes¶

trace_id / detection_id / scorer_id — UUIDs (validated; returns validation_error if malformed)
language on pisama_generate_source_fix — one of python, typescript, javascript, go, rust, java, ruby
All since params — ISO-8601 datetime string (2026-06-08T00:00:00Z)
page / per_page — integers; per_page max 100

Authentication¶

The API key is sent as Authorization: Bearer <key> on every request. Keys are per-tenant and do not scope to read/write yet — one key grants all 12 tools. Separate ingest vs read keys are planned for a future release.

Example prompts¶

Once connected, try these from your IDE chat:

pisama: show me the last 5 traces with failures

pisama: are there any high-confidence detections in the last hour?

pisama: get fix suggestions for detection abc123 and apply the safest one

pisama: create a scorer called "tool-efficiency" that rates how efficiently
        the agent uses tools — penalize redundant calls

Troubleshooting¶

"No MCP server named pisama" — check that cwd in the config points to pisama/backend and that python -m app.mcp.server --api-key x --tenant-id y starts without error.

validation_error: Unknown tool — the server is running an older version; pull latest main and reinstall.

upstream_http_error 401 — API key is wrong or expired. Regenerate at pisama.ai/settings/api-keys.

upstream_http_error 404 on tenant — tenant UUID mismatch. Your tenant ID is the UUID shown in the URL when you log into the dashboard.

upstream_unreachable — the Pisama backend is not reachable from the machine running the MCP server. For local dev, start the backend first (uvicorn app.main:app --port 8000).