MCP Server¶

Pisama ships a local Model Context Protocol server in the pisama Python package. Claude Code, Claude Desktop, Cursor, Windsurf, and other MCP clients can analyze traces without a Pisama account or backend connection.

Installation¶

Install the package with its MCP extra:

python -m pip install "pisama[mcp]"

Verify the CLI and detector registry:

pisama --version
pisama detectors

Client configuration¶

Add this server to your MCP client's configuration:

{
  "mcpServers": {
    "pisama": {
      "command": "pisama",
      "args": ["mcp-server"]
    }
  }
}

The server uses stdio transport and runs the detector suite on the same machine as the client. It does not require PISAMA_API_KEY, a tenant ID, or network access.

Tool reference¶

Tool	Description	Required arguments
`pisama_analyze`	Run all 32 registered detectors on a trace.	`trace`
`pisama_detect`	Run one named detector on a trace.	`detector`, `trace`
`pisama_status`	Summarize analyses and findings in the current MCP session.	none
`pisama_explain`	Explain a failure type, common causes, and detection method.	`failure_type`

The trace argument accepts a JSON object, a JSON string, or a path ending in .json or .jsonl.

Example prompts¶

Analyze ./traces/latest.json with Pisama and explain every finding.

Run only the loop detector on ./trace.json.

Explain the persona_drift failure type and then check ./session.jsonl for it.

Troubleshooting¶

The client cannot find pisama. Use the absolute path returned by command -v pisama as the configuration's command, or install the package in an environment available to the client.

The server reports that the MCP extra is missing. Reinstall with python -m pip install "pisama[mcp]".

The client reports an unknown tool. Run python -m pip install --upgrade "pisama[mcp]", restart the MCP client, and confirm the four tool names above.

A trace cannot be loaded. Pass a JSON object, JSON text, or an absolute .json or .jsonl path readable by the MCP server process.