cBioPortal MCP Server

Instructions

Implementation Reference

• cbioportal_mcp/endpoints/genes.py:216-322 (handler)

  Primary handler implementation in GenesEndpoints class. Fetches molecular profiles for the study to identify the mutation profile, then queries the mutations endpoint with appropriate gene ID type (Entrez or Hugo), study, sample list, and pagination parameters. Handles errors and pagination metadata.
  @handle_api_errors("get mutations in gene") async def get_mutations_in_gene( self, gene_id: str, study_id: str, sample_list_id: str, page_number: int = 0, page_size: int = 50, sort_by: Optional[str] = None, direction: str = "ASC", limit: Optional[int] = None, ) -> Dict: """ Get mutations in a specific gene for a given study and sample list, with pagination support. Uses the /molecular-profiles/{molecularProfileId}/mutations endpoint with GET and query parameters. The molecularProfileId is dynamically determined based on the studyId. """ try: molecular_profiles_response = await self.api_client.make_api_request( f"studies/{study_id}/molecular-profiles" ) if ( isinstance(molecular_profiles_response, dict) and "api_error" in molecular_profiles_response ): return { "error": f"Failed to fetch molecular profiles for study {study_id} to find mutation profile", "details": molecular_profiles_response, } mutation_profile_id = None if isinstance(molecular_profiles_response, list): for profile in molecular_profiles_response: if profile.get("molecularAlterationType") == "MUTATION_EXTENDED": mutation_profile_id = profile.get("molecularProfileId") break if not mutation_profile_id: return { "error": f"No MUTATION_EXTENDED molecular profile found for study {study_id}" } api_call_params = { "studyId": study_id, "sampleListId": sample_list_id, "pageNumber": page_number, "pageSize": page_size, "direction": direction, } if sort_by: api_call_params["sortBy"] = sort_by if limit == 0: api_call_params["pageSize"] = FETCH_ALL_PAGE_SIZE if str(gene_id).isdigit(): api_call_params["entrezGeneId"] = gene_id else: api_call_params["hugoGeneSymbol"] = gene_id endpoint = f"molecular-profiles/{mutation_profile_id}/mutations" mutations_from_api = await self.api_client.make_api_request( endpoint, method="GET", params=api_call_params ) if ( isinstance(mutations_from_api, dict) and "api_error" in mutations_from_api ): return { "error": "API error fetching mutations", "details": mutations_from_api, "request_params": api_call_params, } if not isinstance(mutations_from_api, list): return { "error": "Unexpected API response type for mutations (expected list)", "details": mutations_from_api, "request_params": api_call_params, } api_might_have_more = len(mutations_from_api) == api_call_params["pageSize"] if ( api_call_params["pageSize"] == FETCH_ALL_PAGE_SIZE and len(mutations_from_api) < FETCH_ALL_PAGE_SIZE ): api_might_have_more = False mutations_for_response = mutations_from_api if limit and limit > 0 and len(mutations_from_api) > limit: mutations_for_response = mutations_from_api[:limit] total_items_in_response = len(mutations_for_response) return { "mutations": mutations_for_response, "pagination": { "page": page_number, "page_size": page_size, "total_found": total_items_in_response, "has_more": api_might_have_more, }, } except Exception as e: return { "error": f"An unexpected error occurred in get_mutations_in_gene: {str(e)}" }
• cbioportal_mcp/server.py:97-131 (registration)

  Registration of all MCP tools, including 'get_mutations_in_gene'. The method name is listed in tool_methods (line 113) and registered via self.mcp.add_tool(method) in the loop.
  """Register tool methods as MCP tools.""" # List of methods to register as tools (explicitly defined) tool_methods = [ # Pagination utilities "paginate_results", "collect_all_results", # Studies endpoints "get_cancer_studies", "get_cancer_types", "search_studies", "get_study_details", "get_multiple_studies", # Genes endpoints "search_genes", "get_genes", "get_multiple_genes", "get_mutations_in_gene", # Samples endpoints "get_samples_in_study", "get_sample_list_id", # Molecular profiles endpoints "get_molecular_profiles", "get_clinical_data", "get_gene_panels_for_study", "get_gene_panel_details", ] for method_name in tool_methods: if hasattr(self, method_name): method = getattr(self, method_name) self.mcp.add_tool(method) logger.debug(f"Registered tool: {method_name}") else: logger.warning(f"Method {method_name} not found for tool registration")
• cbioportal_mcp/server.py:249-271 (handler)

  Delegate/wrapper handler in the main CBioPortalMCPServer class. This is the method directly registered as the MCP tool and delegates to the detailed implementation in GenesEndpoints.
  async def get_mutations_in_gene( self, gene_id: str, study_id: str, sample_list_id: str, page_number: int = 0, page_size: int = 50, sort_by: Optional[str] = None, direction: str = "ASC", limit: Optional[int] = None, ) -> Dict: """Get mutations in a specific gene for a given study and sample list, with pagination support.""" return await self.genes.get_mutations_in_gene( gene_id, study_id, sample_list_id, page_number, page_size, sort_by, direction, limit, )