MCP & Plugin
Reference
On this page
Files the tooling reads and writes
| Path | Written by | Commit it? |
|---|---|---|
.opexia/agentmap.lock | opexia audit, /opexia:secure | ✅ Yes — its value is the reviewable diff |
.opexia/shipcheck.yml | You | ✅ Yes |
.opexia/devlog/ + graph.jsonl | /opexia:log | ✅ Yes |
.opexia-wal/spans.jsonl | The SDK | ❌ No — add to .gitignore |
.mcp.json | You or the plugin | ✅ Yes |
Environment variables
| Variable | Used by | Default | Description |
|---|---|---|---|
PXCORE_MODEL | pxcore-mcp, pxcore | claude-fable-5 | Active model, selecting the calibration profile |
CLAUDE_PLUGIN_ROOT | Plugin configs | (set by Claude Code) | Plugin install root |
OPEXIA_API_KEY | /opexia:instrument, opexia shipcheck | — | Workspace API key |
Console scripts
| Script | Purpose |
|---|---|
opexia | Subcommand dispatcher — shipcheck, audit, live |
pxcore-mcp | The MCP server — stdio or HTTP |
pxcore-proxy | In-path compression proxy for Claude Code |
All three install with pip install opexia-trace.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| MCP server not listed in Claude Code | .mcp.json not picked up | Restart Claude Code; confirm pxcore-mcp is on PATH |
pxcore-mcp: command not found | Package not installed, or wrong venv | pip install opexia-trace; check the active environment |
| Compression never activates | Model uncalibrated — the default is off | /opexia:compress status, then /opexia:compress calibrate |
| Content stays text unexpectedly | Classified exact, or the net-loss guard fired | Expected — exact never images, and prose is often costlier as an image |
| Token count went up | Imaging prose or small blocks | Current versions guard against this — upgrade opexia-trace |
/opexia:log does nothing | init not run in this repo | /opexia:log init |
/opexia:secure finds nothing | No system instructions detected | Pass an explicit path or glob |
Plugin commands missing from /help | Plugin not installed or not enabled | /plugin install opexia, then restart |
| HTTP transport refuses connections | Server not running, or wrong port | Start pxcore-mcp --http --port 8765 and match the client URL |
See also
- REST API Reference — all 100 endpoints (93 Read API + 9 Ingest, 2 shared).
- SDK Reference —
opexia-tracefor Python, plus the TypeScript / OpenTelemetry route.