GTEx MCP Server

Instructions

Implementation Reference

• src/handlers/expression-handlers.ts:111-204 (handler)

  The primary handler function for the 'get_median_gene_expression' tool. Validates inputs, fetches data from API client, groups by gene, sorts tissues by expression, computes statistics, and formats a detailed markdown response with top expressing tissues and summaries.
  async getMedianGeneExpression(args: any) { if (!args.geneIds || !Array.isArray(args.geneIds) || args.geneIds.length === 0) { throw new Error('geneIds parameter is required and must be a non-empty array of gene IDs'); } if (args.geneIds.length > 60) { return { content: [{ type: "text", text: "Maximum 60 genes can be processed at once. Please reduce the number of genes." }] }; } const result = await this.apiClient.getMedianGeneExpression( args.geneIds, args.datasetId || 'gtex_v8', args.tissueIds ); if (result.error) { return { content: [{ type: "text", text: `Error retrieving median gene expression: ${result.error}` }], isError: true }; } const expressions = result.data || []; if (expressions.length === 0) { return { content: [{ type: "text", text: "No median expression data found for the specified genes." }] }; } // Group by gene for better organization const geneGroups: { [key: string]: any[] } = {}; expressions.forEach(expr => { const key = `${expr.geneSymbol} (${expr.gencodeId})`; if (!geneGroups[key]) { geneGroups[key] = []; } geneGroups[key].push(expr); }); let output = `**Median Gene Expression (${expressions.length} tissue-gene combinations)**\n`; output += `Dataset: ${expressions[0]?.datasetId || args.datasetId}\n\n`; Object.entries(geneGroups).forEach(([geneKey, geneExpressions]) => { output += `### ${geneKey}\n`; // Sort by expression level (highest first) const sortedExpressions = geneExpressions.sort((a, b) => b.median - a.median); // Show top expressing tissues const topCount = Math.min(10, sortedExpressions.length); output += `**Top ${topCount} expressing tissues:**\n`; sortedExpressions.slice(0, topCount).forEach((expr, index) => { const tissueDisplayName = this.getTissueDisplayName(expr.tissueSiteDetailId); output += ` ${index + 1}. **${tissueDisplayName}**: ${expr.median.toFixed(3)} ${expr.unit}\n`; }); if (sortedExpressions.length > topCount) { output += ` ... and ${sortedExpressions.length - topCount} more tissues\n`; } // Expression summary const medians = sortedExpressions.map(e => e.median); const expressionStats = { max: Math.max(...medians), min: Math.min(...medians), mean: medians.reduce((sum, val) => sum + val, 0) / medians.length, nonZeroCount: medians.filter(val => val > 0).length }; output += `\n**Expression Summary:**\n`; output += ` • Tissues analyzed: ${sortedExpressions.length}\n`; output += ` • Highest expression: ${expressionStats.max.toFixed(3)} ${sortedExpressions[0]?.unit || 'TPM'}\n`; output += ` • Mean expression: ${expressionStats.mean.toFixed(3)} ${sortedExpressions[0]?.unit || 'TPM'}\n`; output += ` • Tissues with detectable expression: ${expressionStats.nonZeroCount}\n\n`; }); return { content: [{ type: "text", text: output.trim() }] }; }
• src/index.ts:73-90 (schema)

  Tool schema definition in the listTools response, specifying the name, description, and input schema (gencodeId required, datasetId optional). Note: handler adapts 'gencodeId' to 'geneIds' array.
  name: "get_median_gene_expression", description: "Get median gene expression levels across tissues", inputSchema: { type: "object", properties: { gencodeId: { type: "string", description: "GENCODE gene ID (e.g., ENSG00000223972.5)" }, datasetId: { type: "string", description: "GTEx dataset ID (default: gtex_v8)", default: "gtex_v8" } }, required: ["gencodeId"] } },
• src/index.ts:631-635 (registration)

  Tool call dispatching logic in the main CallToolRequestHandler. Matches tool name and invokes the expressionHandlers.getMedianGeneExpression method with adapted arguments.
  if (name === "get_median_gene_expression") { return await expressionHandlers.getMedianGeneExpression({ geneIds: args?.gencodeId ? [args.gencodeId] : [], datasetId: args?.datasetId });
• src/utils/api-client.ts:302-323 (helper)

  Supporting API client method that makes the HTTP request to GTEx Portal's /expression/medianGeneExpression endpoint, handling query params, response parsing, and error formatting.
  async getMedianGeneExpression( gencodeIds: string[], datasetId: string = 'gtex_v8', tissueSiteDetailIds?: string[] ): Promise<GTExApiResponse<MedianGeneExpression[]>> { try { const queryParams = this.buildQueryParams({ gencodeId: gencodeIds, datasetId, tissueSiteDetailId: tissueSiteDetailIds, page: 0, itemsPerPage: 1000 }); const response = await this.axiosInstance.get(`/expression/medianGeneExpression?${queryParams}`); return { data: response.data.data, paging_info: response.data.paging_info }; } catch (error) { return error as GTExApiResponse<MedianGeneExpression[]>; } }