MCP

Perseval bundles an MCP server so coding agents can query structured trace evidence without scraping the GUI or copying raw trace JSON into a prompt.

The installed path is:

/Applications/Perseval.app/Contents/Resources/perseval-mcp

The server uses MCP over stdio. It does not open another OTLP listener. When the GUI owns the workspace, MCP processes connect through Perseval’s private user-only local owner socket. Leave the GUI open if you want agents to inspect the live committed workspace.

Register the absolute bundled path in Codex, Claude, or another MCP-compatible client:

{
  "mcpServers": {
    "perseval": {
      "command": "/Applications/Perseval.app/Contents/Resources/perseval-mcp",
      "env": {
        "PERSEVAL_MCP_READ_ENABLED": "true"
      }
    }
  }
}

Restart the MCP client after changing its configuration. If the GUI uses an explicit custom workspace, give the MCP process the same PERSEVAL_WORKSPACE_DIR. Ordinary default-workspace users do not need that variable.

• list_projects
• list_sessions
• list_runs
• list_failure_groups
• get_failure_group
• inspect_finding
• get_evidence_trace
• get_eval_batch_job
• get_verification_report

Responses are committed, versioned, paged, and bounded. The default configuration excludes raw payload bodies. Cursors bind tool, scope, filter, and snapshot; stale or mismatched cursors fail closed.

1. List projects and choose one explicit project.
2. List finalized runs or the highest-priority unresolved groups.
3. Inspect one representative finding and its missing facts.
4. Retrieve the bounded evidence trace and surrounding spans.
5. Correlate the evidence with code, propose a fix, and ask a human to review it in the GUI.

MCP does not bypass finding or eval review. The current server cannot accept a finding, create an eval, reveal a raw payload, or change configuration.

After the client reports a successful connection, ask:

List Perseval projects, then list the latest finalized runs in one explicit project. Do not reveal payload bodies.

A valid connection negotiates the configured protocol, exposes nine tools, and returns bounded structured data.

• confirm the command is the absolute bundled path;
• confirm PERSEVAL_MCP_READ_ENABLED=true;
• restart the MCP client;
• verify the app bundle still contains an executable Contents/Resources/perseval-mcp.

Open Settings → Workspace and compare the effective path with the MCP environment. Remove stale overrides or use the same explicit path in both processes.

Use a smaller page size or narrower project/build/session filter. Maximum pages and evidence spans are protocol-bounded.

The owner socket is local and user-only. Stdio clients still inherit the permissions of the launching user, so only register the executable with MCP clients you trust. Payload reveal, compute, and write capability classes remain unavailable in this milestone.