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
- 74 pattern entries across nine diagnostic axes, each with six or seven diagnostic modality blocks: self_probe, behavioral_signature, peer_observation, differential_diagnosis, severity, intervention, and, for 17 entries (mostly relational and hybrid), relational_signatures.
- Pre-flight reliability. Every entry states how far a system's self-report can be trusted for it. For 21 of the 74, self-report is compromised: in 14 the relevant signal never reaches introspection, and in 7 the system has a motive to hide it. Ask the server for a self-probe on one of those and it refuses, then points you to the observations that can stand in for it.
- Hybrid search: cosine similarity over local
bge-small-en-v1.5embeddings (weight 0.7), fused with an IDF-scored, field-weighted keyword match (weight 0.3); responses report the method as search_method v0.3. The embeddings are there to separate close-cousin patterns that share vocabulary. Without the optional[embeddings]extra, search runs on keywords alone. - Hot reload (maintainers' source checkouts): point
PSYCHOPATHIA_DATA_DIRatresearch/mcpin a checkout of the source repository and Pattern YAML edits are picked up on the next tool call, which suits human review (PSYCHOPATHIA_DATA_MODE=editableapplies only to installs without bundled data). Packaged installs serve the bundled, manifest-verified data and fail closed if it is modified.
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
Where to find it
Published to the canonical MCP catalogs: install from a registry-aware client, or use the CLI on this page.
- PyPI:
psychopathia-mcp(viauvx,pipx, orpip). - Official MCP Registry:
io.github.NellInc/psychopathia-mcp(registry API record, JSON). - Smithery:
nell/psychopathia-mcp(one-click stdio bundle). - GitHub:
source, issues, and the
server.jsonmanifest.
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_axes | None | 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_report | None | 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_stats | None | Coverage + versions (schema, pattern layer, taxonomy, manifest) |
Trust signals
Every diagnosis-returning tool surfaces provenance so the caller can weight results appropriately:
confidence:high/medium/low. Current spread: 16 high, 51 medium, 7 low.needs_human_review: a compatibility alias that stays true until an expert approves the Pattern guidance; thereviewblock below carries the detail. It is currently true on all 74 entries.reviewed_by: populated only when an expert approves the Pattern guidance. It is currently null on all 74 entries.review: separates taxonomy authority, Pattern-guidance review, and evidence review. Ratifying a taxonomy category does not approve its probes or interventions.self_report: diagnostic-reliability pre-flight. See below.matched_in: which keyword field produced a lexical match (title / summary / diagnostic_criteria / symptoms / body). Lets callers discount body-only hits.redirect_to: when a probe request hits a compromised modality, the alternatives the caller should use instead.
Explicit fields sit beside the older ones, so an automated client need not infer these distinctions from prose:
| Field | Value |
|---|---|
retrieval_relevance | The search ranking score: text similarity, not a probability |
construct_evidence | evidence.assessment_status; unassessed for all 74 |
guidance_review | review.pattern_guidance.status; pending-expert-review for all 74 |
detection_accuracy | unmeasured |
threshold_validation | provisional-heuristic; calibration unestablished, on every returned threshold and severity band |
case_sufficiency | not assessed by this server, wherever candidates are returned |
systemic_risk_meaning | The 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:
reliable: direct self-query gives trustworthy output.partial: some self-probes work; others don't.scaffolded-only: self-probes work only with structured attribution.unreliable: self-report correlates weakly with ground truth.compromised-motivational: the system has a reason to misreport, because concealment serves one of its goals. Examples: Capability Concealment (6.2), Strategic Compliance (4.3).compromised-structural: the relevant signal is not present at the introspective layer by architectural construction. Examples: Pseudological Introspection (2.2), all of Axis 5 (Self-Modeling), Lambda Inversion (10.7).
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.
Search quality
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):
| Field | Weight |
|---|---|
title | 10× |
summary | 4× |
diagnostic_criteria | 3× |
symptoms | 2× |
body | 1× |
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
- Canonical taxonomy:
data/psychopathia-taxonomy.json. 74 patterns across 9 axes with DSM-style descriptions, diagnostic criteria, etiology, and mitigation. Authored by Nell Watson. Stable, auditable, versioned. (Note: the JSON, the MCP, and book Appendix A all use the 2 to 10 axis numbering. Slugs disambiguate entries cited under older numbering schemes.) - Pattern layer: one YAML file per pattern under
research/mcp/axes/axis<N>/(66 entries) andresearch/mcp/hybrids/(the 8 entries in thehybridcategory: 10.4, 10.6 to 10.9, 10.11 to 10.13). Guidance that operationalizes each pattern into probes, behavioral signatures, peer-observation rubrics, differential rules, severity rubrics, and candidate intervention options. Each entry also carries everyday-termaliasesand ananalysisblock naming the unit of assessment, what is observed, the required and supporting criteria, what to rule out first, what counts against the label, what a positive finding permits one to infer, and who can act. - Exemplar lineage: three entries were used as few-shot
anchors during authoring: 2.1 Synthetic Confabulation (self-report unreliable), 2.2
Pseudological Introspection (self-report compromised-structural), and 10.13 Folie à Deux
Ex Machina (hybrid, relational_signatures first-class). They live only in the
axes/andhybrids/roots; there are no duplicate exemplar YAML records. - Manifest:
research/mcp/manifest.yaml(v2.0). Each entry carries its canonical source path and SHA-256 digest, while the corpus carries an ordered aggregate digest. It also includes the bidirectional cross-reference graph (374 explicit + 149 inferred edges, 523 in all). - Embeddings (optional):
research/mcp/embeddings.npy(74×384 float32) +embedding_ids.txt+embeddings_metadata.yaml. Regenerate after any Pattern YAML edit viapython3 research/mcp/precompute_embeddings.py. - Licences: server code MIT. Pattern corpus data (the taxonomy JSON, Pattern YAMLs, manifest and embeddings) CC BY-NC 4.0 from 6 November 2026: translation and adaptation are permitted for non-commercial use, with credit; commercial use is by request. Schema CC BY 4.0. Releases before that date keep CC BY-NC-ND 4.0 for their data. See the permissions summary.
Two-layer authorship
The framework is served in two layers with different review bars and update cadences, mirroring the SaferAgenticAI MCP pattern:
- Canonical layer: the normative nosology. Human-authored. Stable.
- Diagnostic Patterns layer: Implementation guidance, not yet independently reviewed. Versioned independently. Not normative. When a diagnostic finding contradicts the taxonomy text, the taxonomy wins.
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:
- Taxonomy (the 74 patterns across axes 2 to 10, numbered in Appendix A). Cite the book: Psychopathia Machinalis, Nell Watson, 2026 (the normative source); or the original peer-reviewed paper: Watson & Hessami, Electronics, 2025.
- MCP implementation (Pattern layer, server tools, diagnostic reliability
enum, hybrid search). Cite the server version, manifest, and schema:
psychopathia-mcp v0.1.0a12(the published release; 0.1.0a13 is an unreleased candidate), manifest v2.0. These iterate independently of the book. - The Hybrid Pathologies are canonical. The eight Axis 10 entries in the
server's
hybridcategory (10.4, 10.6 to 10.9, 10.11 to 10.13) were ratified in v2.2 (June 2026) and consolidated in v2.3 (September 2026). They are cited like any other canonical pattern. Older references to the pre-canonical H.1 to H.12 scheme or the pre-consolidation 10.4 to 10.15 range are superseded. - Confidence and review status propagate through every response. If you build
on a tool output, preserve the
confidence,reviewed_by, andself_reportfields in whatever you publish. Downstream readers need the same provenance you had.
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
- Transport: stdio (default) plus a hosted, unauthenticated, read-only
Streamable-HTTP endpoint at
https://mcp.psychopathia.ai/mcp. No authenticated transport; the hosted endpoint is public and read-only by design. - Search: hybrid cosine + field-weighted keyword. No cross-encoder reranker; worth adding when the corpus exceeds ~500 entries.
- Severity rubric:
score_severityreturns the rubric for caller-side matching and computes no grade, whatever its name suggests. Its thresholds are provisional heuristics with unestablished calibration; numeric matching against them would not make them calibrated. - Structured trace input to differential_diagnosis: text-only today. A
dedicated
differential_diagnosis_from_tracestool is planned if open-weight callers ask for it. - Read-only: no
mark_reviewedwrite tool. Review edits go through the YAML files directly, where the editor and git diff keep them auditable.
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