GTEx MCP Server

Instructions

Implementation Reference

• src/handlers/association-handlers.ts:232-314 (handler)

  The main handler function that implements the tool logic for get_multi_tissue_eqtls. It validates input, calls the API client, processes the multi-tissue eQTL meta-analysis results, and formats them into a structured Markdown response.

  async getMultiTissueEQTLs(args: any) {
    if (!args.geneId || typeof args.geneId !== 'string') {
      throw new Error('geneId parameter is required and must be a gene ID string');
    }
  
    const result = await this.apiClient.getMultiTissueEQTLs(
      args.geneId,
      args.variantId,
      args.datasetId || 'gtex_v8'
    );
  
    if (result.error) {
      return {
        content: [{
          type: "text",
          text: `Error retrieving multi-tissue eQTL data: ${result.error}`
        }],
        isError: true
      };
    }
  
    const metaResults = result.data || [];
    if (metaResults.length === 0) {
      return {
        content: [{
          type: "text",
          text: `No multi-tissue eQTL results found for gene: ${args.geneId}`
        }]
      };
    }
  
    let output = `**Multi-Tissue eQTL Meta-Analysis**\n`;
    output += `Gene: ${args.geneId}\n`;
    output += `Dataset: ${metaResults[0]?.datasetId}\n`;
    output += `Results: ${metaResults.length} gene-variant combinations\n\n`;
  
    metaResults.forEach((result, index) => {
      output += `### Result ${index + 1}: ${result.variantId}\n`;
      output += `**Meta p-value:** ${result.metaP.toExponential(2)}\n`;
      output += `**Gene:** ${result.gencodeId}\n\n`;
  
      if (result.tissues && Object.keys(result.tissues).length > 0) {
        // Sort tissues by m-value (posterior probability)
        const tissueEntries = Object.entries(result.tissues);
        tissueEntries.sort((a, b) => b[1].mValue - a[1].mValue);
  
        output += `**Tissue-Specific Results:**\n`;
        const topTissues = tissueEntries.slice(0, 10); // Show top 10 tissues
        
        topTissues.forEach(([tissueName, tissueData]) => {
          const tissueDisplayName = this.getTissueDisplayName(tissueName);
          output += `  **${tissueDisplayName}**:\n`;
          output += `    • m-value (posterior prob): ${tissueData.mValue.toFixed(4)}\n`;
          output += `    • p-value: ${tissueData.pValue.toExponential(2)}\n`;
          output += `    • NES: ${tissueData.nes.toFixed(3)}\n`;
          output += `    • Standard error: ${tissueData.se.toFixed(4)}\n`;
        });
  
        if (tissueEntries.length > 10) {
          output += `  ... and ${tissueEntries.length - 10} more tissues\n`;
        }
  
        // Summary statistics
        const mValues = tissueEntries.map(([, data]) => data.mValue);
        const nesValues = tissueEntries.map(([, data]) => data.nes);
        const significantTissues = tissueEntries.filter(([, data]) => data.mValue > 0.5);
  
        output += `\n**Summary:**\n`;
        output += `  • Tissues analyzed: ${tissueEntries.length}\n`;
        output += `  • Tissues with m-value > 0.5: ${significantTissues.length}\n`;
        output += `  • Max m-value: ${Math.max(...mValues).toFixed(4)}\n`;
        output += `  • Mean |NES|: ${(nesValues.map(n => Math.abs(n)).reduce((sum, n) => sum + n, 0) / nesValues.length).toFixed(3)}\n`;
      }
      output += '\n';
    });
  
    return {
      content: [{
        type: "text",
        text: output.trim()
      }]
    };
  }

• src/index.ts:301-317 (schema)

  Tool schema definition in the list of available tools, specifying the input schema with required gencodeId and optional datasetId.

  name: "get_multi_tissue_eqtls",
  description: "Get multi-tissue eQTL meta-analysis results", 
  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:693-697 (registration)

  Registration and dispatch logic in the main CallToolRequest handler that maps the tool name to the AssociationHandlers.getMultiTissueEQTLs method.

  if (name === "get_multi_tissue_eqtls") {
    return await associationHandlers.getMultiTissueEQTLs({
      geneId: args?.gencodeId,
      datasetId: args?.datasetId
    });

• src/utils/api-client.ts:503-524 (helper)

  Supporting API client method that performs the HTTP request to the GTEx Portal API endpoint /association/metasoft to fetch raw multi-tissue eQTL meta-analysis data.

  async getMultiTissueEQTLs(
    gencodeId: string,
    variantId?: string,
    datasetId: string = 'gtex_v8'
  ): Promise<GTExApiResponse<MultiTissueEQTL[]>> {
    try {
      const queryParams = this.buildQueryParams({
        gencodeId,
        variantId,
        datasetId,
        page: 0,
        itemsPerPage: 250
      });
      const response = await this.axiosInstance.get(`/association/metasoft?${queryParams}`);
      return { 
        data: response.data.data,
        paging_info: response.data.paging_info
      };
    } catch (error) {
      return error as GTExApiResponse<MultiTissueEQTL[]>;
    }
  }