paiml-mcp-agent-toolkit

Installation | MCP Server | Usage | Features | Examples | Documentation

Table of Contents

• What is PMAT?
• Installation
• MCP Server
• Usage
• Features
• Architecture

What is PMAT?

PMAT (Pragmatic Multi-language Agent Toolkit) provides everything needed to analyze code quality and generate AI-ready context:

• Context Generation - Deep analysis for Claude, GPT, and other LLMs
• Technical Debt Grading - A+ through F scoring with 6 orthogonal metrics
• Mutation Testing - Test suite quality validation (85%+ kill rate)
• Repository Scoring - Quantitative health assessment (0-289 scale, 11 categories)
• Git History RAG - Semantic search across commit history with RRF fusion
• Semantic Search - Natural language code discovery
• Compliance Governance - 157 checks across code quality, best practices, and reproducibility
• Design by Contract - Toyota Way contract profiles with checkpoint validation and rescue protocols
• Autonomous Kaizen - Toyota Way continuous improvement with auto-fix and commit
• MCP Integration - 20 tools for Claude Code, Cline, and AI agents over stdio and HTTP (identical surfaces), validated end-to-end for concurrent multi-agent (ultracode) workflows — see MCP Server
• Quality Gates - Pre-commit hooks, CI/CD integration, .pmat-gates.toml config
• 20+ Languages - Rust, TypeScript, Python, Go, Java, C/C++, Lua, Lean, and more

Part of the PAIML Stack, following Toyota Way quality principles (Jidoka, Genchi Genbutsu, Kaizen).

Annotated Code Search

Every result includes TDG grade, Big-O complexity, git churn, code clones, pattern diversity, fault annotations, call graph, and syntax-highlighted source.

Installation

# Install from crates.io
cargo install pmat

Note for macOS Users: If you experience issues installing via rustup, we recommend installing/updating Rust using Homebrew: brew install rust before running cargo install pmat.

# Or from source (latest)
git clone https://github.com/paiml/paiml-mcp-agent-toolkit
cd paiml-mcp-agent-toolkit && cargo install --path .

MCP Server

PMAT is an MCP server first and a CLI second. One binary serves three surfaces, and they share one tool registry — you pick a surface, not a feature set.

New in 3.32.0: mcp-http moved into the default feature set. cargo install pmat now gives you the HTTP transport; the old --features mcp-http dance is gone. Compiling the transport in does not open a socket — only pmat serve binds one.

Quickstart — stdio

Claude Code launches pmat as a subprocess. Nothing to keep running, nothing to authenticate.

cargo install pmat
claude mcp add --scope user pmat -- pmat --mode mcp
claude mcp list
# pmat: pmat --mode mcp - ✔ Connected

Claude Desktop takes the same command as JSON, in its own claude_desktop_config.json:

{
  "mcpServers": {
    "pmat": { "command": "pmat", "args": ["--mode", "mcp"] }
  }
}

For clients that cannot pass flags, MCP_VERSION=1 pmat starts the identical server. Smoke-test the stdio surface without any client at all:

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  | pmat --mode mcp 2>/dev/null | jq -r '.result.tools | length'
# 19

Quickstart — HTTP

One server, many clients. Copy-paste the whole block:

cargo install pmat

export PMAT_MCP_HTTP_TOKEN='pmat-mcp-demo-token-0123456789'   # >= 16 chars; use your own
pmat serve --transport http --port 8765 &
#   pmat MCP (streamable HTTP) listening on http://127.0.0.1:8765/
#     auth: Bearer, from PMAT_MCP_HTTP_TOKEN; unauthenticated requests get 401
#     tools: 20
sleep 2

claude mcp add --scope user --transport http pmat http://127.0.0.1:8765/ \
  --header "Authorization: Bearer $PMAT_MCP_HTTP_TOKEN"
claude mcp list
# pmat: http://127.0.0.1:8765/ (HTTP) - ✔ Connected

The server binds 127.0.0.1 unless you pass --host. To reach it from another machine, bind an externally routable address and treat PMAT_MCP_HTTP_TOKEN as a real secret — the tool surface can read and analyse any path the server process can read.

Four gotchas that cost an hour each

1. MCP is served at the root path /, not /mcp. There is no path prefix.

for p in / /mcp /health; do
  printf '%-7s %s\n' "$p" "$(curl -s -o /dev/null -w '%{http_code}' -X POST "http://127.0.0.1:8765$p" \
    -H "Authorization: Bearer $PMAT_MCP_HTTP_TOKEN" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json, text/event-stream" \
    -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}')"
done
# /       200
# /mcp    404
# /health 404

2. PMAT_MCP_HTTP_TOKEN is mandatory and must be at least 16 characters. Below that the server refuses to start rather than falling back to serving unauthenticated — the underlying pmcp transport answers every request when no auth provider is wired, so "no token" has to mean "no server". Requests with no token, or a wrong one, get 401.

PMAT_MCP_HTTP_TOKEN=too-short-123 pmat serve --transport http --port 8765
# Error: PMAT_MCP_HTTP_TOKEN must be at least 16 characters; got 13

3. Hand-rolled clients must send Accept: application/json, text/event-stream. The streamable transport rejects the request without it, and curl -f turns that into an empty string with no message — so probe with plain curl -s while debugging.

curl -s -w '\n-> HTTP %{http_code}\n' -X POST http://127.0.0.1:8765/ \
  -H "Authorization: Bearer $PMAT_MCP_HTTP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
# {"jsonrpc":"2.0","error":{"code":-32700,"message":"Accept header must include application/json or text/event-stream"},"id":null}
# -> HTTP 406

4. There is no /health endpoint. GET /health is a 404, so a curl -f .../health readiness loop never turns green and never says why. Probe with a real tools/list call instead:

curl -s -X POST http://127.0.0.1:8765/ \
  -H "Authorization: Bearer $PMAT_MCP_HTTP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  | jq -r '.result.tools | length'
# 19

No MCP session id is involved: initialize returns no Mcp-Session-Id header, and tools/call works directly — with or without a preceding initialize.

HTTP is not a reduced surface

Both transports are built from the same registry, so HTTP serves all 20 tools, not a subset. The tools/list payloads are byte-identical:

printf '%s\n%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"p","version":"1"}}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  | pmat --mode mcp 2>/dev/null \
  | jq -Sc 'select(.id==2)|.result.tools|sort_by(.name)' > /tmp/pmat-stdio-tools.json

curl -s -X POST http://127.0.0.1:8765/ \
  -H "Authorization: Bearer $PMAT_MCP_HTTP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  | jq -Sc '.result.tools|sort_by(.name)' > /tmp/pmat-http-tools.json

cmp /tmp/pmat-stdio-tools.json /tmp/pmat-http-tools.json && echo "identical"
# identical

The 19: analyze_complexity, analyze_satd, analyze_dead_code, analyze_dag, analyze_deep_context, analyze_big_o, analyze_reachability, analyze_hardcoded_paths, analyze_vacuous_tests, quality_gate, quality_proxy, generate_context, scaffold_project, git_operation, pmat_query_code, pmat_get_function, pmat_find_similar, pmat_index_stats, pdmt_deterministic_todos. Names and descriptions are also committed as the machine-checked manifest mcp.json at the repository root, regenerated from the server's own registrations — so it cannot drift from what t