Ensembl MCP Server

Instructions

Implementation Reference

• src/index.ts:1448-1478 (handler)

  The main handler function that executes the get_xrefs tool: validates input using isValidXrefArgs, queries Ensembl REST API at /xrefs/id/{gene_id} with species, external_db, and all_levels parameters, formats response as JSON, handles errors.

  private async handleGetXrefs(args: any) {
    if (!isValidXrefArgs(args)) {
      throw new McpError(ErrorCode.InvalidParams, 'Invalid xref arguments');
    }
  
    try {
      const species = this.getDefaultSpecies(args.species);
  
      const params: any = { species };
  
      if (args.external_db) {
        params.external_db = args.external_db;
      }
  
      if (args.all_levels) {
        params.all_levels = 1;
      }
  
      const response = await this.apiClient.get(`/xrefs/id/${args.gene_id}`, { params });
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(response.data, null, 2),
          },
        ],
      };
    } catch (error) {
      return this.handleError(error, 'fetching cross-references');
    }

• src/index.ts:864-865 (registration)

  Registers the tool handler in the CallToolRequestSchema switch statement, mapping 'get_xrefs' calls to handleGetXrefs method.

  case 'get_xrefs':
    return this.handleGetXrefs(args);

• src/index.ts:739-751 (registration)

  Tool metadata registration in ListToolsRequestSchema response: defines name, description, and inputSchema for discovery.

    name: 'get_xrefs',
    description: 'Get external database cross-references for genes',
    inputSchema: {
      type: 'object',
      properties: {
        gene_id: { type: 'string', description: 'Ensembl gene ID' },
        species: { type: 'string', description: 'Species name (default: homo_sapiens)' },
        external_db: { type: 'string', description: 'Specific external database (optional)' },
        all_levels: { type: 'boolean', description: 'Include transcript and translation xrefs (default: false)' },
      },
      required: ['gene_id'],
    },
  },

• src/index.ts:243-255 (schema)

  Input validation type guard (schema) for get_xrefs tool arguments.

  const isValidXrefArgs = (
    args: any
  ): args is { gene_id: string; species?: string; external_db?: string; all_levels?: boolean } => {
    return (
      typeof args === 'object' &&
      args !== null &&
      typeof args.gene_id === 'string' &&
      args.gene_id.length > 0 &&
      (args.species === undefined || typeof args.species === 'string') &&
      (args.external_db === undefined || typeof args.external_db === 'string') &&
      (args.all_levels === undefined || typeof args.all_levels === 'boolean')
    );
  };

• src/index.ts:119-129 (helper)

  TypeScript interface defining the expected structure of Ensembl cross-reference (xref) data.

  interface EnsemblXref {
    primary_id: string;
    display_id: string;
    version?: string;
    description?: string;
    dbname: string;
    info_type: string;
    info_text?: string;
    linkage_annotation?: string[];
  }