README.md
Enables structured queries and data analysis of cancer genomics information.
CIViC MCP Server
This is a Cloudflare Workers-based Model Context Protocol (MCP) server that provides tools for querying the CIViC (Clinical Interpretation of Variants in Cancer) API. The server converts GraphQL responses into queryable SQLite tables using Durable Objects for efficient data processing.
The CIViC database is a crowd-sourced repository of clinical interpretations of cancer variants. This MCP server enables structured queries and data analysis of cancer genomics information through natural language interactions with AI assistants.
MCP Specification Compliance
This server implements MCP 2025-06-18 specification with the following compliance status:
✅ Implemented Features
- Structured Tool Output: Tools return structured JSON data with
_metafields - Protocol Version Headers: Supports
MCP-Protocol-Versionheader handling - Title Fields: Tools include human-friendly titles for display
- Meta Fields: Extensive use of
_metafields for additional context - Error Handling: Proper error responses with structured content
🔄 Partially Implemented
- Tool Annotations: Configuration ready but SDK integration pending
readOnlyHint,destructiveHint,idempotentHint,openWorldHintdefined- Need SDK update to support annotation parameters
⚠️ Pending Implementation
- Streamable HTTP Transport: Currently uses SSE transport
- Action Required: Migrate from HTTP+SSE to Streamable HTTP per MCP 2025-03-26
- Status: Architecture change needed for proper implementation
- OAuth 2.1 Authorization: Not implemented
- Action Required: Add OAuth 2.1 support for secure remote server access
- Components: Authorization Server discovery, Resource Indicators (RFC 8707)
- JSON-RPC Batching: Properly removed (was added in 2025-03-26, removed in 2025-06-18)
Tool Annotations Reference
The server defines comprehensive tool annotations for MCP clients:
// GraphQL Query Tool
annotations: {
readOnlyHint: false, // Creates/modifies data in SQLite
destructiveHint: false, // Non-destructive data staging
idempotentHint: false, // Different queries produce different results
openWorldHint: true // Interacts with external CIViC API
}
// SQL Query Tool
annotations: {
readOnlyHint: true, // Only reads data
destructiveHint: false, // Cannot modify data (read-only SQL)
idempotentHint: true, // Same query produces same results
openWorldHint: false // Operates on closed SQLite database
}
Future Updates Required
1. Transport Layer Migration
// Current: SSE Transport (deprecated)
CivicMCP.serveSSE("/sse").fetch(request, env, ctx)
// Target: Streamable HTTP Transport (MCP 2025-03-26+)
// Implementation requires MCP SDK architectural updates
2. Tool Annotation Integration
// Current: SDK doesn't support 5-argument tool() method
this.server.tool(name, description, schema, handler, annotations) // ❌
// Target: Find correct SDK pattern for annotations
// May require MCP SDK update or different approach
3. Authorization Framework
// Required: OAuth 2.1 integration with:
// - Authorization Server discovery (.well-known endpoints)
// - Resource Indicators (RFC 8707)
// - Dynamic client registration (RFC 7591)
// - PKCE-enabled authorization code flow
Specification Changelog Summary
MCP 2025-03-26 (Implemented)
- ✅ Tool annotations framework
- ⚠️ Streamable HTTP transport (pending)
- ✅ Audio data support (infrastructure ready)
- ⚠️ OAuth 2.1 authorization (pending)
MCP 2025-06-18 (Current Target)
- ✅ Structured tool output
- ✅ Enhanced
_metafields - ✅ Protocol version headers
- ✅ Title fields for tools
- ❌ JSON-RPC batching removed (properly removed)
- ⚠️ Enhanced authorization security (pending)
Features
- GraphQL to SQL Conversion: Automatically converts CIViC API responses into structured SQLite tables
- Efficient Data Storage: Uses Cloudflare Durable Objects with SQLite for data staging and querying
- Smart Response Handling: Optimizes performance by bypassing staging for small responses, errors, and schema introspection queries
- Two-Tool Pipeline:
civic_graphql_query: Executes GraphQL queries and stages large datasetscivic_query_sql: Enables SQL-based analysis of staged data
Installation & Configuration
Prerequisites
- A Cloudflare account
- Wrangler CLI installed
- Claude Desktop app
Deploy to Cloudflare Workers
Clone this repository:
git clone <repository-url> cd civic-mcp-serverInstall dependencies:
npm installDeploy to Cloudflare Workers:
npm run deployAfter deployment, you'll get a URL like:
https://civic-mcp-server.YOUR_SUBDOMAIN.workers.dev
Configure Claude Desktop
Add this configuration to your claude_desktop_config.json file:
Tools (2)
civic_graphql_queryExecutes GraphQL queries against the CIViC API and stages large datasets into SQLite tables.civic_query_sqlEnables SQL-based analysis and filtering of cancer genomics data staged in the SQLite database.Configuration
claude_desktop_config.json
{
"mcpServers": {
"civic": {
"command": "npx",
"args": [
"-y",
"@quentincody/civic-mcp-server"
]
}
}
}Try it
→Query the CIViC API for the latest clinical interpretations of BRAF V600E mutations.
→Run a GraphQL query to fetch all evidence items for lung cancer and stage them for analysis.
→Use SQL to filter the staged CIViC data for variants with a high clinical significance level.
→Analyze the relationship between specific cancer variants and drug responses using the staged SQLite tables.
→List the available GraphQL schema fields for the CIViC genomics database.