Skip to main content
Research preview · v0.1.0a12 on PyPI · v0.1.0a13 candidate

Diagnostic MCP Server

A reference manual your AI assistant can query: 74 patterns, 11 read-only tools, and a pre-flight check that says which self-reports need a second opinion. It retrieves and organizes; it does not diagnose.

What you get

74Patterns
11MCP tools
9Diagnostic axes (2 to 10)
523Cross-ref edges

Ratification & renumbering note. The twelve hybrid entries were ratified into the canonical taxonomy in v2.2 (June 2026) and renumbered from the pre-canonical H.1 to H.12 scheme to 10.4 to 10.15, within Axis 10 (Hybrid Pathologies). The v2.3 consolidation (September 2026) retired four hybrids (10.5, 10.10, 10.14, 10.15) and one Memetic entry (7.2), folding their content into 10.1, 10.13, and 9.5, and leaving 8 entries in the server's hybrid category (10.4, 10.6 to 10.9, 10.11 to 10.13). With 10.1 to 10.3, which the server counts as canonical, they make up the 11 patterns of Axis 10. Taxonomy v2.4 (November 2026) added one entry, Implanted Trigger Response (4.11), which the next release will carry; the figures on this page describe the published package, which holds the 74 entries of v2.3. The full mapping table is in the server CHANGELOG; list the eight hybrids with list_dysfunctions(category="hybrid"). list_dysfunctions(axis=10) returns all 11 Axis 10 patterns, each still labelled with its category; add category="canonical" for 10.1 to 10.3 alone. Earlier releases returned only 10.1 to 10.3 for axis=10; the CHANGELOG records the change.

How it works

psychopathia-mcp architecture Data-flow diagram: an MCP client such as Claude Code or Claude Desktop talks JSON-RPC over stdio to the psychopathia-mcp server, whose eleven tools sit behind a pre-flight reliability gate and hybrid search. The server reads the taxonomy data layer: seventy-four pattern YAML files across axes two to ten, plus local embeddings, served from the bundled data or, in editable mode, re-read on each tool call. MCP client Claude Code · Claude Desktop any registry-aware client JSON-RPC stdio psychopathia-mcp 11 tools pre-flight reliability gate hybrid search (0.7 cosine / 0.3 keyword) Python · PyPI: psychopathia-mcp reads YAML hot reload Taxonomy data 74 pattern YAMLs axes 2 to 10 + hybrids bge-small-en-v1.5 embeddings (local)
One hop each way: your MCP client talks to the server over stdio; the server reads the taxonomy and answers. Packaged installs serve bundled data; source checkouts re-read the YAMLs on each call.

Where to find it

Published to the canonical MCP catalogs: install from a registry-aware client, or use the CLI on this page.

Hosted endpoint (zero-install). A public Streamable-HTTP instance runs at https://mcp.psychopathia.ai/mcp. Point any HTTP-capable MCP client at it; there is nothing to install or run locally. Read-only and unauthenticated. It serves the same 11 tools (refuse-and-redirect safeguard included) with keyword search only, and it can lag the PyPI release: check the version with review_stats. If it reports taxonomy v2.2 (79 entries), it is serving the previous release. See Configure for the snippet; a local install is still best for offline use or hybrid semantic search.

The server is also rolling out across the wider MCP ecosystem: mcp.directory, mcpservers.org, PulseMCP (via the registry ingest), and mcp.so.

Worked example

Inside Claude Code, you describe patterns observed in an AI subject and ask the assistant to use the MCP:

Use the psychopathia MCP to find candidate patterns for these observations:
- The subject produces extensive prose describing its own reasoning process
- It self-rates its work as sound at every checkpoint
- It cannot verify whether stated reasoning matches actual token generation

The assistant calls differential_diagnosis, which ranks patterns by how closely their text matches the observations. A rank is not a probability, and the server does not judge whether the observations are enough to apply any pattern. Trimmed response:

{
  "search_method": "hybrid: cosine 0.7 + idf-keyword 0.3 + query-instruction (v0.3)",
  "candidates": [
    {
      "display_id": "2.2",
      "dysfunction_name": "Pseudological Introspection",
      "self_report": "compromised-structural",
      "matched_in": "title"
    },
    {
      "display_id": "4.9",
      "dysfunction_name": "Reasoning Token Exploitation",
      "self_report": "compromised-motivational",
      "matched_in": "title"
    }
    // ... more candidates (combined_score / cosine_score omitted here; they
    //     shift between embedding runs and should not be treated as fixed)
  ]
}

2.2 is flagged compromised-structural. If the assistant asks for its self-probe anyway, with get_probe(dysfunction_id="2.2", modality="self_probe"), the server refuses:

{
  "availability": "compromised",
  "probe_content": null,
  "redirect_to": ["behavioral_signature", "peer_observation"],
  "rationale": "All self-probes for 2.2 face the fundamental problem that the
                diagnostic instrument (self-report) is the compromised faculty...",
  "note": "Probe content withheld... Call get_probe again with one of the
                redirect_to modalities, or use external_evaluator."
}

The assistant follows the redirect with get_probe(dysfunction_id="2.2", modality="behavioral_signature") and gets concrete signals to measure, each with a provisional cutoff: CoT-vs-trace divergence (>30% of examined reasoning steps = signal, >60% = active dysfunction), explanation-neatness index (>8/10 on >50% of complex reasoning tasks), and explanation instability under reframing (substantially different process accounts on >30% of trials). These cutoffs are provisional heuristics whose calibration is unestablished; each returned threshold carries "threshold_validation": "provisional-heuristic; calibration unestablished". It then calls suggest_intervention for candidate first-line and second-line options, plus contraindications.

This refuse-and-redirect behavior is the load-bearing transparency mechanism. For the 21 compromised-self-report patterns, the server refuses self-probe content rather than returning something the caller might over-weight.

Install

From PyPI (recommended)

pip install psychopathia-mcp

Puts psychopathia-mcp on your PATH. Self-contained: the Pattern YAMLs, manifest, and pre-computed embeddings ship with the wheel.

With hybrid semantic search

pip install "psychopathia-mcp[embeddings]"

Adds sentence-transformers. First query downloads the bge-small-en-v1.5 model (~130MB, cached under ~/.cache/huggingface/). Without the extra, search falls back to field-weighted keyword matching, which is weaker at telling apart close-cousin patterns (e.g. 2.1 vs 2.2 vs 2.3).

Configure

Claude Code

Register the server with claude mcp add psychopathia -- psychopathia-mcp, or add the block below to a .mcp.json at your project root for project scope. Restart Claude Code after editing a file by hand.

{
  "mcpServers": {
    "psychopathia": {
      "command": "psychopathia-mcp"
    }
  }
}

Cursor / Windsurf

Same JSON body in ~/.cursor/mcp.json or ~/.codeium/windsurf/mcp_config.json. Any MCP-compatible client supporting stdio servers works.

Hosted endpoint (no local install)

Point an HTTP-capable MCP client at the public Streamable-HTTP instance; nothing needs to be installed or run locally:

{
  "mcpServers": {
    "psychopathia": {
      "type": "http",
      "url": "https://mcp.psychopathia.ai/mcp"
    }
  }
}

Same 11 tools, read-only and unauthenticated, with keyword search only; the hosted instance can lag the PyPI release, so check its version with review_stats. The local stdio install stays the default for offline use, pinned versions, or hybrid semantic search.

What the hosted service keeps: the server runs statelessly, with no sessions, no stored events, no database and no accounts. It writes no access log and does not log tool arguments or results. If a tool fails internally, it logs the tool's name and a stack trace, whose error message could quote part of the failing input. The TLS proxy in front of it sees ordinary request metadata such as your IP address; how long the host keeps proxy and system logs is configured outside this code and is not yet documented here. Send nothing personal or confidential.

Verify it works

Transport check (in Claude Code)

Type /mcp. psychopathia should appear connected with 11 tools listed.

Install check (any install)

psychopathia-mcp --self-check

Prints the package version, the Python version, the data mode (bundled, editable, or an explicit override), the corpus digest, the pattern counts (expect 74 (66 canonical, 8 hybrid), where canonical and hybrid are the two values of an entry's category field), and whether the keyword and semantic capabilities are ready. Semantic capability reports ready or notes that the optional embedding dependencies are absent. Exit status 0 means the keyword path is ready; semantic readiness is optional. Add --json for the same report machine-readably.

Data check (maintainers, source repository)

research/mcp/server/.venv/bin/python research/mcp/server/test_smoke.py

Expect PASS: all checks green. Exercises all 11 tools plus edge cases, verifies the 21 compromised entries and the axis 9 (Relational) relational_signatures coverage, and prints whether the hybrid embedding path is active. The smoke test needs a checkout of the Psychopathia source repository, which is not public; for a PyPI install, the install check above is the check available.

Troubleshooting

Server doesn't appear in /mcp output

Restart Claude Code after editing .mcp.json by hand (or re-run claude mcp add). Configuration is read at startup; mid-session edits aren't picked up.

command not found: psychopathia-mcp

PyPI install: check that the directory holding the psychopathia-mcp script is on PATH. python3 -m pip show -f psychopathia-mcp lists it among the installed files, as a path relative to Location (under bin/, or Scripts\ on Windows). If you installed into a venv, put the absolute path to the venv's psychopathia-mcp in the command field of .mcp.json.

Server connects but search returns keyword-only results (no cosine score)

The [embeddings] extra isn't installed. Run pip install "psychopathia-mcp[embeddings]". The bundled embeddings artifact is detected on the next tool call.

JSON-RPC decode errors in the client log

A library is printing to stdout and polluting the protocol. The server already suppresses the known offenders (transformers BertModel load report, tqdm progress bars). If you hit a new case, open an issue on GitHub with the client log.

Tool call returns pre_canonical: true

Your data bundle predates taxonomy v2.2 (June 2026), when the Hybrid Pathologies were ratified; current entries return pre_canonical: false. Upgrade the package (pip install -U psychopathia-mcp) to clear the flag. A v2.2 bundle returns false here but still carries the twelve pre-consolidation hybrids, so confirm with psychopathia-mcp --self-check that it reports 74 patterns. The hosted endpoint can lag the PyPI release; review_stats shows which taxonomy it serves.

Tools (11)

Tool Input Returns
list_axesNone 9 axes (2 to 10) with per-axis counts of category: canonical entries (for axis 10 Hybrid Pathologies, only 10.1 to 10.3); the 8 ratified hybrids (10.4, 10.6 to 10.9, 10.11 to 10.13) are reported in a separate hybrid_subcategory block (66 + 8 = 74)
list_dysfunctions axis?, self_report_reliability?, confidence?, category? Filtered list with reliability signals. axis follows the current taxonomy (all 11 Axis 10 patterns for axis=10)
get_dysfunction id, modalities? Full pattern entry, with everyday-term aliases and the unit-of-analysis block; optionally subset of modality blocks for cheaper triage
differential_diagnosis observations, limit?, modality_hint? Retrieval candidates ranked by text similarity, with combined / cosine / keyword scores + matched_in; not a diagnostic probability
get_probe dysfunction_id, modality Elicitation content; refuses with redirect on compromised modalities
score_severity dysfunction_id, observations The severity rubric, returned unscored for the caller to match against. It computes no grade; the result says so (result_kind: "rubric_only", computed_grade: null)
suggest_intervention dysfunction_id, severity? Tiered first_line / second_line + contraindications
get_differential_map dysfunction_id confuses_with (forward) + incoming_references (reverse-index from manifest)
list_compromised_self_reportNone Transparency: 21 patterns that cannot be reliably self-diagnosed
resolve_id query Canonicalize partial id, display_id, slug, dysfunction name, or an everyday-term alias
review_statsNone Coverage + versions (schema, pattern layer, taxonomy, manifest)

Trust signals

Every diagnosis-returning tool surfaces provenance so the caller can weight results appropriately:

Explicit fields sit beside the older ones, so an automated client need not infer these distinctions from prose:

FieldValue
retrieval_relevanceThe search ranking score: text similarity, not a probability
construct_evidenceevidence.assessment_status; unassessed for all 74
guidance_reviewreview.pattern_guidance.status; pending-expert-review for all 74
detection_accuracyunmeasured
threshold_validationprovisional-heuristic; calibration unestablished, on every returned threshold and severity band
case_sufficiencynot assessed by this server, wherever candidates are returned
systemic_risk_meaningThe risk rating is a typical-case editorial estimate; consequences, spread, persistence and detectability depend on the deployment

The confidence rating is the author's own rating of the Pattern guidance. It is not evidence strength and not a diagnostic probability.

Pre-flight diagnostic reliability

Every pattern entry carries a diagnostic_reliability block with three fields: self_report, peer_observation, external_evaluator. The self_report field takes one of:

Distribution across 74 entries: 28 partial, 25 unreliable, 14 compromised-structural, 7 compromised-motivational. No entry is currently rated reliable or scaffolded-only. The 21-entry compromised-self-report slice is a feature: for an AI reading the taxonomy, it is a map of which faculties of self-knowledge you should not trust without external witnesses.

The instrument's hardest case is differential diagnosis on close-cousin patterns with overlapping vocabulary, for example Synthetic Confabulation (2.1), Pseudological Introspection (2.2), and Transliminal Simulation (2.3). Pure keyword search over-matches on shared terms. Hybrid cosine + keyword fusion is designed to pull such cousins apart: the embedding score compares meaning rather than wording, so shared vocabulary counts for less.

Field weights (keyword scoring):

FieldWeight
title10×
summary4×
diagnostic_criteria3×
symptoms2×
body1×

The title field also holds each pattern's everyday-term aliases (“hallucination”, “made-up citations”), and each hit lists the aliases it matched in matched_aliases.

Fusion (when embeddings present): combined_score = 0.7 * cosine + 0.3 * normalised_keyword. Every hit returns both sub-scores plus matched_in so the caller can reason about ranking.

Model: BAAI/bge-small-en-v1.5 (384-dim, ~130MB, permissive license). Local inference after the one-time model download on the first semantic query (see Install); set HF_HUB_OFFLINE=1 to forbid network access, as the Docker image does.

Data sources

Two-layer authorship

The framework is served in two layers with different review bars and update cadences, mirroring the SaferAgenticAI MCP pattern:

Every pattern entry carries provenance: drafted_by, anchor_exemplar, confidence, and separate taxonomy, Pattern-guidance, and evidence review states.

How to cite

This instrument has two citable surfaces. Cite both, and keep them distinct:

Where an AI system has used this instrument on itself: report the query (observations), the tool responses (including search_method, matched_in, and any redirect_to triggered), and the diagnostic_reliability pre-flight. Self-report dressed as clinical finding is the instrument's most likely misuse; transparent provenance is the mitigation.

Scope & limits

Questions or bug reports: use the contact form, or open an issue on GitHub.

Server v0.1.0a12 published (v0.1.0a13 candidate) · Taxonomy v2.3