CIViC MCP Server

Execute JavaScript code against the CIViC GraphQL API. Code runs in a sandboxed V8 isolate with:

• gql.query(queryString, variables?) — execute GraphQL queries (returns data directly, e.g. result.gene not result.data.gene)
• schema.types(), schema.type(name), schema.search(query) — explore the schema
• schema.queryRoot() — list available query entry points with args
• schema.enumValues(name), schema.inputType(name) — inspect enums and input types
• console logging (log, warn, error, info) — captured output

Domain-specific helper functions and quirks are documented below.

The last expression or return value is the result.

Use schema.queryRoot() to discover available query fields.

STAGING: Large responses (>30KB) are auto-staged into SQLite. When this happens, gql.query returns {__staged: true, data_access_id, schema, tables_created, total_rows, message}. Scalar properties from the original response are preserved on the staged object.

When staging occurs:

1. Check result.__staged === true
2. Read any preserved scalars (result.count, result.total, etc.)
3. Return the staging metadata — the caller will use civic_query_data with the data_access_id to explore the data with SQL

DO NOT try to access .results, .data, .entries, .items on a staged response — those arrays were replaced by SQLite tables.

For advanced use: api.query(data_access_id, sql) and db.queryStaged(data_access_id, sql) are available to query staged data within the same execution (returns {results, row_count}, max 1000 rows, SELECT only).

SCRATCHPAD: db.stage(data, tableName?) stages any array/object into SQLite and returns {data_access_id, tables_created, total_rows}. Use this to persist computed or filtered results for SQL queries.

IMPORTANT: Use pagination params (first/after, limit/offset) to keep responses small. If you need large datasets, let them auto-stage and return the staging info.

SERVER NOTES: --- CIViC quirks --- Gene lookup uses entrezSymbol, NOT symbol: gql.query('{ gene(entrezSymbol: "EGFR") { id name } }') Genes by list: gql.query('{ genes(entrezSymbols: ["EGFR","BRAF"]) { nodes { id name } } }')

Variants require gene ID (integer), NOT gene symbol: Step 1: const g = await gql.query('{ gene(entrezSymbol: "BRAF") { id } }'); Step 2: const v = await gql.query('{ variants(geneId: ' + g.data.gene.id + ') { nodes { id name } } }');

EvidenceItem.status is a scalar enum (string), NOT an object. Correct: status (returns string like "ACCEPTED") WRONG: status { name } — this will error

Known field name mappings (common mistakes): direction -> evidenceDirection (on EvidenceItem) level -> evidenceLevel type -> evidenceType direction -> assertionDirection (on Assertion) type -> assertionType cytobands -> cytogeneticRegions (on Region) iscn -> iscnName (on RegionVariant)

Feature types: Gene, Factor, Fusion, Region Regions represent chromosome/cytoband-level features (e.g., 17p Deletion) Region variants carry ISCN notation in their 'iscnName' field

Region lookup: gql.query('{ region(id: 62862) { id name featureType cytogeneticRegions { chromosome band } } }') Cytoband typeahead: gql.query('{ cytogeneticRegionTypeahead(queryTerm: "17p") { id name chromosome band } }')

Execute GraphQL queries against the CIViC (Clinical Interpretation of Variants in Cancer) GraphQL API. Large responses are staged in SQLite for SQL querying.

KEY QUERY PATTERNS — CIViC uses non-standard argument names:

• Gene by symbol: { gene(entrezSymbol: "EGFR") { id name description } }
• Genes by list: { genes(entrezSymbols: ["EGFR","BRAF"]) { nodes { id name } } }
• Variants by gene ID: { variants(geneId: 19) { nodes { id name } } } (requires gene ID from gene query — does NOT accept gene symbol)
• Evidence items: { evidenceItems(first: 10) { nodes { id status } } } (status is a scalar enum/string, not an object)
• Region by ID: { region(id: 62862) { id name featureType cytogeneticRegions { chromosome band } variants { nodes { id name iscnName } } } }
• Regions list: { regions(first: 10) { nodes { id name featureType cytogeneticRegions { chromosome band } } } } (filterable by name, iscnName — Regions are chromosome/cytoband-level features for karyotype, FISH, CMA, WGS variants)
• Cytoband typeahead: { cytogeneticRegionTypeahead(queryTerm: "17p") { id name chromosome band } }
• Region variant names: { regionVariantNamesForFeatureId(featureId: 62862) }

FEATURE TYPES: CIViC has 4 feature types — Gene, Factor, Fusion, Region. Regions represent chromosome/cytoband-level variation (e.g., 17p Deletion, 1q21.2 Amplification). Region variants carry ISCN (2024) notation in their 'iscnName' field (e.g., del(17p), amp(1q21.2)).

Use introspection { __type(name: "Query") { fields { name args { name type { name } } } } } to discover additional fields. Results will be staged to SQLite.

Execute read-only SQL queries against staged CIViC data in SQLite. Use the data_access_id from a GraphQL query to access the corresponding dataset.

🏷️ TOOL ANNOTATIONS:

• Type: Read-only, Idempotent, Closed-world
• Interactions: Local SQLite database queries only
• Side Effects: None (read-only operations)
• Caching: Data is pre-staged and cached
• Rate Limits: None (local operations)
• MCP 2026-07-28 Compliant: ✅

Search the CIViC GraphQL schema for the query roots, types, and fields matching your keywords — so you write a civic_execute query with REAL field names instead of guessing. Call this FIRST when you don't already know the schema. Returns top-level entry points plus matching Type.field signatures with their arguments and return types.