GTEx MCP Server

Instructions

Implementation Reference

• src/index.ts:420-446 (registration)

  Tool registration in the ListTools handler, defining name, description, and input schema for get_variants

  {
    name: "get_variants",
    description: "Get genetic variants in a genomic region",
    inputSchema: {
      type: "object",
      properties: {
        chr: {
          type: "string",
          description: "Chromosome (e.g., chr1, chr2, chrX)"
        },
        start: {
          type: "integer",
          description: "Start position (1-based)"
        },
        end: {
          type: "integer",
          description: "End position (1-based)"
        },
        datasetId: {
          type: "string",
          description: "GTEx dataset ID (default: gtex_v8)",
          default: "gtex_v8"
        }
      },
      required: ["chr", "start", "end"]
    }
  },

• src/handlers/reference-handlers.ts:313-382 (handler)

  Main handler function executing the get_variants tool logic: input validation, API call to retrieve variants, and formatted text response generation.

  async getVariants(args: any) {
    if (!args.snpId && !args.variantId && !args.chromosome) {
      throw new Error('At least one of snpId, variantId, or chromosome must be provided');
    }
  
    const result = await this.apiClient.getVariants({
      snpId: args.snpId,
      variantId: args.variantId,
      datasetId: args.datasetId || 'gtex_v8',
      chromosome: args.chromosome,
      pos: args.positions ? (Array.isArray(args.positions) ? args.positions : [args.positions]) : undefined,
      page: args.page || 0,
      itemsPerPage: args.itemsPerPage || 250
    });
  
    if (result.error) {
      return {
        content: [{
          type: "text",
          text: `Error retrieving variant information: ${result.error}`
        }],
        isError: true
      };
    }
  
    const variants = result.data || [];
    if (variants.length === 0) {
      return {
        content: [{
          type: "text",
          text: "No variants found matching the specified criteria."
        }]
      };
    }
  
    let output = `**Variant Information (${variants.length} variants)**\n`;
    output += `Dataset: ${variants[0]?.datasetId}\n\n`;
  
    variants.forEach((variant, index) => {
      output += `### ${index + 1}. ${variant.variantId}\n`;
      output += `**Genomic Information:**\n`;
      output += `  • Position: ${variant.chromosome}:${variant.pos.toLocaleString()}\n`;
      output += `  • Alleles: ${variant.ref} → ${variant.alt}\n`;
      if (variant.snpId && variant.snpId !== 'nan') {
        output += `  • dbSNP ID: ${variant.snpId}\n`;
      }
      if (variant.b37VariantId) {
        output += `  • GRCh37 ID: ${variant.b37VariantId}\n`;
      }
      
      output += `\n**Population Genetics:**\n`;
      output += `  • MAF ≥1%: ${variant.maf01 ? 'Yes' : 'No'}\n`;
      
      if (variant.shorthand) {
        output += `  • Shorthand: ${variant.shorthand}\n`;
      }
      output += '\n';
    });
  
    if (result.paging_info && result.paging_info.totalNumberOfItems > variants.length) {
      output += `**Note:** Showing ${variants.length} of ${result.paging_info.totalNumberOfItems} total results.\n`;
    }
  
    return {
      content: [{
        type: "text",
        text: output.trim()
      }]
    };
  }

• src/utils/api-client.ts:253-272 (helper)

  API client helper method that performs the HTTP request to GTEx Portal API endpoint /dataset/variant to fetch variant data.

  async getVariants(params: GetVariantsParams): Promise<GTExApiResponse<Variant[]>> {
    try {
      const queryParams = this.buildQueryParams({
        snpId: params.snpId,
        variantId: params.variantId,
        datasetId: params.datasetId || 'gtex_v8',
        chromosome: params.chromosome,
        pos: params.pos,
        page: params.page || 0,
        itemsPerPage: params.itemsPerPage || 250
      });
      const response = await this.axiosInstance.get(`/dataset/variant?${queryParams}`);
      return { 
        data: response.data.data,
        paging_info: response.data.paging_info
      };
    } catch (error) {
      return error as GTExApiResponse<Variant[]>;
    }
  }

• src/types/gtex-types.ts:425-433 (schema)

  TypeScript interface defining parameters for the getVariants API call used by the handler and client.

  export interface GetVariantsParams {
    snpId?: string;
    variantId?: string;
    datasetId?: string;
    chromosome?: string;
    pos?: number[];
    page?: number;
    itemsPerPage?: number;
  }

• src/types/gtex-types.ts:72-84 (schema)

  TypeScript interface defining the structure of variant data returned by the API.

  export interface Variant {
    snpId: string;
    b37VariantId: string;
    pos: number;
    maf01: boolean;
    variantId: string;
    alt: string;
    chromosome: string;
    snpIdUpper: string;
    datasetId: string;
    ref: string;
    shorthand: string;
  }