Analyze pgsc_calc polygenic score matching QC from summary and optional variant log files, and render Markdown reports.
Assess a single score or whole run: variant match rate, weight coverage, strand/ambiguous handling, exclusions, per-chromosome coverage, SNV/indel matching, match types, inferred pgsc_calc settings, and pass/fail verdicts.
Flag structural warnings such as absent chromosomes, unmatched indels, missing positions, excluded duplicates, retained ambiguous variants, suspected build mismatch, and log/summary mismatch.
Return compact score indexes for large runs and full detail for requested PGS IDs.
Render a focused single-score report or run-wide Markdown QC report, optionally write it to a file, and place an assistant-written interpretation at the top.
Provide raw measurements and observations for interpretation using the bundled match-QC guide.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@pgs-mcp Check QC for results/cohort/match/cohort_summary.csv and cohort_log.csv.gz; which scores are risky?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that evaluates polygenic score matching from pgsc_calc in a target population, flags matching warnings and silent errors, and contextualizes findings into a user report.
The pgsc_calc package passes or fails each polygenic score based on a single number: variant match rate. However, the percentage of variants matched is an incomplete picture of matching accuracy.
For example: A score can match a threshold-passing percentage of its variants, say 72%, while keeping only 16% of the total effect weight, because the unmatched variants were the large-effect ones.
This server reads pgsc_calc's matching outputs and gives the full picture: weight coverage, which variants were lost, where, and the likely upstream cause, as well as analysis of strand flips, ambiguous alleles, and missing data. It gives recommendations for scores to drop from analysis even if they passed the threshold, as well as upstream data checks to reduce unmatched variants. The tools are adaptable to one score or a run of hundreds.
uv (brew install uv, or see the uv docs)
An MCP client, such as Claude Code
Match log and match summary files from a pgsc_calc run (specifically, the match_variants step ahead of pgs calculation)
Related MCP server: just-prs-mcp
Claude Code
claude mcp add pgs-mcp -- uvx --from git+https://github.com/csjohnson23/pgs-mcp pgs-mcpOther MCP clients: add this to your client's MCP configuration (for Claude
Desktop, claude_desktop_config.json) and restart the client.
{
"mcpServers": {
"pgs-mcp": {
"command": "uvx",
"args": ["--from", "git+https://github.com/csjohnson23/pgs-mcp", "pgs-mcp"]
}
}
}The server runs locally, so your match files stay on your machine. pgsc_calc's match files describe variants, not people, and hold no individual genotypes. Only per-score summaries, such as match rates, weight coverage and the positions of the largest unmatched score variants, are passed to your assistant.
pgsc_calc writes both files for this MCP to the match/ folder for each sampleset:
results/<sampleset>/match/<sampleset>_summary.csv match summary (required)
results/<sampleset>/match/<sampleset>_log.csv.gz variant-level match log (recommended)The log is required for effect weight coverage, the largest lost variants, per-chromosome coverage and indel matching, which is where most problems show up. The first log read is cached, but expect initial runtime of up to a minute for larger logs (>3GB).
Ask your assistant for PGS matching analysis in plain language, with the paths to your files. For example:
Check the match QC for
results/cohort/match/cohort_summary.csvwith the logresults/cohort/match/cohort_log.csv.gz. Which scores should I be careful with, and why?
Look at PGS000316 in detail. What was lost, and does it matter?
Write a QC report for the whole run to
qc_report.md, with your interpretation at the top.
For a run with many scores you get a run-level picture first (problems shared by every score, such as missing chromosomes or no indels in your data), then scores grouped by pattern. Ask about specific scores for full detail.
You can also start the guided interpretation directly: in Claude Code type
/mcp__pgs-mcp__interpret_match_qc; in Claude Desktop it is listed under the connected server in
the message box.
examples/ holds a small synthetic run: three made-up scores matched against a target
that looks like imputed array data, with no chrX and no indels. pgsc_calc passes all three. To try
it in about a minute:
git clone https://github.com/csjohnson23/pgs-mcp && cd pgs-mcp
uv run pgs-mcp qc examples/example_summary.csv --log examples/example_log.csv --reportOr, with the server installed, ask your assistant to check the match QC for
examples/example_summary.csv with the log examples/example_log.csv.
From the report, trimmed and with score names shortened:
Run-wide warnings
CHROM_ABSENT: No score variant found in the target on chromosome(s) X (10).
TARGET_LACKS_INDELS: 0 of 7 indel/non-SNV score variants matched while 153 SNVs did.
Score
Variants
Pipeline
Matched
Weight coverage
Warnings
hla_small
15
pass
80.0%
25.3%
SMALL_SCORE, INDELS_UNMATCHED, MISSING_POSITION
large_effect_loss
100
pass
82.0%
47.8%
AMBIGUOUS_RETAINED, CHROM_ABSENT, INDELS_UNMATCHED
mostly_clean
60
pass
98.3%
98.8%
Claude's interpretation, written from the tool output and the interpretation guide:
All three scores passed pgsc_calc, but only
mostly_cleankept its signal: it lost one small variant and 1.2% of its weight.large_effect_lossmatched 82% of its variants but kept 48% of its weight, because the target has no chrX and no indels, and its four indels are its largest-effect variants.hla_smallkept 25% of its weight: its three HLA alleles have no genomic position, so pgsc_calc cannot match them. I would not use those two as is. Check whether chrX and indels were dropped during imputation or QC, and score HLA alleles separately with HLA imputation.
The server reports measurements, never grades. Your assistant interprets them using an interpretation guide that ships with the server, and is told to separate what the data shows from what it infers.
For each score
variant match rate, and the rate excluding strand-ambiguous variants
effect weight coverage: the share of the score's total |effect weight| that matched
the largest-effect unmatched variants, with position and alleles
strand-ambiguous, strand-flipped and excluded shares, with exclusion reasons
SNV and indel matching, match types, and match rate by chromosome
pgsc_calc's own pass/fail verdict, alongside the above
For the run: the pgsc_calc settings implied by the results (min_overlap, whether ambiguous
variants were kept), coverage by chromosome across all scores, and how scores are distributed.
Warnings flag structural problems:
Warning | Meaning |
| No variant on a chromosome was found in your data (run-wide or for one score) |
| Not a single indel matched anywhere in the run |
| All of a score's indels failed to match |
| The score contains entries with no genomic position, such as HLA alleles |
| Variants were dropped for duplicate IDs or tied matches |
| Strand-ambiguous (A/T, C/G) variants were kept and scored as same-strand |
| Fewer than 20 variants, so each one matters |
| Matching is uniformly low (median under 20%) |
| The log and summary appear to come from different runs |
| Only the summary was given; weight-based checks were not possible |
Reports are Markdown: a focused page for one score, or for a run an overview, distributions, chromosome coverage and a table of every score sorted by weight coverage.
The same checks can run without an assistant, which is also a quick way to pre-read a large log:
uvx --from git+https://github.com/csjohnson23/pgs-mcp pgs-mcp qc cohort_summary.csv --log cohort_log.csv.gz --report > qc_report.mdAdd --pgs-id PGS000316 (repeatable) for specific scores, or drop --report for JSON.
Match QC measures coverage, not validity. A perfectly matched score can still be poorly suited to your population; these checks cannot tell you that.
Weight coverage is a proxy. It uses effect sizes without allele frequencies, so it approximates, rather than measures, how much of a score's signal was retained.
Your cohort is unknown to the server. If ancestry, genotyping platform or imputation details matter to an interpretation, tell your assistant, or it will ask.
Cache: aggregated log data is stored in ~/.cache/pgs-mcp (set PGS_MCP_CACHE_DIR to
move it). It is small and safe to delete.
The QC logic in src/pgs_mcp/qc/ is plain Python, independent of MCP.
Tests use small synthetic pgsc_calc outputs in tests/fixtures.
MIT
Assess how well polygenic scores matched a target genotype dataset in pgsc_calc.
Works for a single score or a whole run. Returns raw metrics (variant match rate, weight coverage, strand handling, exclusions, per-chromosome coverage), structural warnings and descriptive observations. Large runs return a compact index of every score; request specific pgs_ids for full detail. Interpret with the guide at pgs://guides/match-qc.
| Name | Required | Description | Default |
|---|---|---|---|
| pgs_ids | No | Optional PGS IDs (e.g. PGS000004) or full accessions to report on. Omit for every score in the file. | |
| log_path | No | Optional path to the variant-level match log, e.g. `{sampleset}_log.csv.gz`. Enables weight, chromosome, indel and match-type metrics. The first read of a large log takes about a minute per few GB; it is then cached. | |
| summary_path | Yes | Path to the pgsc_calc match summary, e.g. `{sampleset}_summary.csv`. |
| Name | Required | Description |
|---|---|---|
| scores | Yes | Full detail for selected scores. |
| dataset | Yes | |
| log_used | Yes | |
| n_scores | Yes | |
| warnings | Yes | |
| chromosomes | Yes | Run-wide coverage over score-variant pairs; a shared variant counts per score. Null without a log, or when specific scores were requested. |
| detail_note | No | Set when detail was limited; explains how to get more. |
| score_index | Yes | |
| genome_builds | Yes | |
| n_pipeline_fail | Yes | |
| n_pipeline_pass | Yes | |
| inferred_settings | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context: raw metrics and warnings are returned, large runs produce a compact score index, and specific pgs_ids produce full detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, then efficiently adds scope, return behavior, large-run handling, and the interpretation guide. Every sentence carries useful information and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema and annotations, the description covers enough for an agent to call the tool correctly: purpose, scope, return behavior, large-run behavior, and guide reference. The main gap is the absence of any mention of the sibling render_qc_report.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema for pgs_ids by explaining the tradeoff: large runs return a compact index, while requesting specific pgs_ids yields full detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: assess how well polygenic scores matched a target genotype dataset in pgsc_calc. It is clear what the tool does, but it never mentions or distinguishes itself from the sibling render_qc_report, so it falls short of the top score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by saying it works for a single score or a whole run, and it points to the match-qc guide for interpretation. However, it gives no explicit when-not guidance and does not explain how to choose this tool versus render_qc_report.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Build a Markdown match QC report for one score or a whole run.
A single score gets a focused report; several scores get a run overview, distributions, chromosome coverage, a table of every score and detail sections. For large runs, pass output_path to write the report to disk rather than returning it.
| Name | Required | Description | Default |
|---|---|---|---|
| pgs_ids | No | Optional PGS IDs (e.g. PGS000004) or full accessions to report on. Omit for every score in the file. | |
| log_path | No | Optional path to the variant-level match log, e.g. `{sampleset}_log.csv.gz`. Enables weight, chromosome, indel and match-type metrics. The first read of a large log takes about a minute per few GB; it is then cached. | |
| output_path | No | Optional .md path to write the report to instead of returning it. | |
| summary_path | Yes | Path to the pgsc_calc match summary, e.g. `{sampleset}_summary.csv`. | |
| interpretation | No | Optional Markdown interpretation to place at the top of the report, written after reading the assess_match_qc output and the interpretation guide. It is placed under an Interpretation heading; a leading heading of your own with that name is merged into it. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations only declaring readOnlyHint=false and openWorldHint=false, the description adds real context: that output is Markdown, that report structure varies by the number of scores, and that the report can be written to disk rather than returned. It does not discuss the cost implications of the underlying data beyond what the schema says about log caching, but the key behavioral tradeoff (return vs write) is disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the purpose and with zero filler. The enumeration of overview/distributions/coverage/table is mildly verbose but does usefully signal what the agent will get back, so it earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return details need not be restated, and the description covers input roles, the single-vs-batch behavioral split, and the disk-output escape hatch for large runs. Nothing an agent needs in order to call this correctly appears to be missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already explains pgs_ids, log_path, output_path, summary_path and interpretation. The description restates the score-count semantics for pgs_ids and the write-to-disk behavior of output_path but adds no syntax, format, or constraint details beyond the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and artifact ('Build a Markdown match QC report') and scopes it to 'one score or a whole run', which is concrete and distinguishable. It never names the sibling assess_match_qc as the contrasting tool, so the boundary between the two is only implied by the parameter text, not stated up front.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear conditional guidance: a single score yields a focused report, several scores yield a run overview, and large runs should use output_path instead of returning the report. It does not explicitly state when to prefer this over assess_match_qc or that this tool should only follow an assessment, leaving that inference to the interpretation parameter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0assess_match_qcrender_qc_reportScored across 2 tools
The two tools have mostly distinct roles: assess_match_qc computes metrics and warnings, while render_qc_report produces a Markdown report. A user might still briefly wonder whether to call assessment before rendering, but the descriptions make the boundary clear enough.
Both names use snake_case and begin with a verb, giving a predictable style. The internal ordering differs slightly between assess_match_qc and render_qc_report, but it is not confusing.
Two tools are quite thin for a server surface, even for a specialized QC workflow. The tools are well-scoped, but the server sits at the borderline of feeling under-provisioned.
The surface covers the core workflow of assessing match QC and rendering a report for single scores or whole runs. Minor gaps may exist around discovery or filtering, but the main lifecycle is represented.
Validate JSON, YAML, XML and CSV with exact line/column errors and silent-corruption warnings.
CSV structural checks and keyed diffs, SRT formatting, MCP result checks and review discovery.
Check a catalogue against The MLC, look up a song's writers, publishers and ISWC, validate CWR files
Read and score Opik traces, experiments, datasets and prompts from your AI assistant.
