Research Biomedical Databases

Research Biomedical Databases

Prerequisites

This skill does nothing on its own. The biomni-research MCP server (an Amazon Bedrock AgentCore Gateway) must be deployed on your AWS account and connected to your AI platform first. If it is not connected, none of the tools below exist and no workflow can run.

• Deployment: See mcp-servers/agentcore-gateway/biomni-research-tools/README.md for full setup. Requires an AWS account with CloudFormation/Lambda/Cognito/IAM/AgentCore permissions, region us-east-1 or us-west-2, and Python 3.12+ with uv. Deploy from agents_catalog/28-Research-agent-biomni-gateway-tools (uv sync → ./scripts/prereq.sh → python scripts/agentcore_gateway.py create --name researchapp-gw). Deploying incurs AWS cost.
• Platform connection: See platforms/ for per-platform guides (Claude Code, Amazon Quick, Kiro, Codex, Strands Agents). MCP-native assistants use the gateway URL directly; header-based setups need a bearer token from source mcp-servers/agentcore-gateway/biomni-research-tools/get-token.sh researchapp.
• Authentication: Cognito M2M bearer token (60-min expiry). Token refresh varies by platform — see your platform guide.
• Verify: Ask the assistant to run x_amz_bedrock_agentcore_search with a query like "protein information" — it should return a ranked tool list. Or from the repo: python agents_catalog/28-Research-agent-biomni-gateway-tools/tests/test_gateway.py --prompt "What proteins interact with TP53?".

Architecture

The Biomni Research Tools are accessed through Amazon Bedrock AgentCore Gateway as an MCP server. The gateway exposes a suite of database query tools via a single endpoint, with optional semantic search to select the most relevant tools per query. The tool set may grow over time; use semantic search to discover what is currently available rather than assuming a fixed count.

User Query
  → AgentCore Gateway (MCP protocol, JWT auth)
    → Semantic search (x_amz_bedrock_agentcore_search) narrows to top-N tools
    → Lambda target executes the selected tool against the external database API
    → Structured results returned

The MCP server name is biomni-research. All tools are available through this single server.

Gateway tool naming: Tools are exposed with a target prefix: DatabaseLambda___query_uniprot, DatabaseLambda___query_clinvar, etc. When calling tools via the gateway MCP endpoint, use the full prefixed name. In this skill's documentation, tools are referenced by their short name (query_uniprot) for readability — prepend DatabaseLambda___ when invoking via the gateway.

Decision Tree: Which Workflow to Use

Match the user's question to the right workflow, then read the corresponding reference file for step-by-step tool calls.

If unsure which workflow applies, use semantic search first — it returns the most relevant tools for any natural language query.

Semantic Search: Tool Discovery

The gateway provides a built-in meta-tool for discovering relevant database tools. This is a gateway-level capability (not a Lambda-backed database tool) — it's injected automatically by AgentCore Gateway when semantic search is configured. It appears in the MCP tool list alongside the database tools.

Use it when:

• The user's question spans multiple domains
• You're unsure which specific tool to call
• You want to reduce tool-loading overhead

Tool: x_amz_bedrock_agentcore_search
Parameter: query (string) — natural language description of what you need
Returns: ranked list of tools with name, description, and inputSchema

Example: User asks "tell me about HER2 variant rs1136201" → Semantic search returns: query_ensembl, query_gwas_catalog, query_clinvar, query_dbsnp → Use those tools in sequence rather than loading the full tool set.

If semantic search is unavailable (gateway configured without searchType: SEMANTIC), fall back to selecting tools manually from the Tool Categories table below.

Tool Categories

Representative tools by category (not exhaustive; the gateway may expose more, so use semantic search to discover the full current set).

For full parameter schemas for each tool, read references/tool-parameter-reference.md.

Gotchas

• query_alphafold requires uniprot_id, NOT a natural language prompt. You must first get the UniProt accession (e.g., P38398) from query_uniprot, then pass it to query_alphafold.
• query_pdb_identifiers requires an identifiers array (e.g., ["1ZNI", "4HHB"]). Use query_pdb with a prompt to search; use query_pdb_identifiers when you already have PDB IDs.
• query_gnomad has a dedicated gene_symbol parameter — use it directly (e.g., gene_symbol: "BRCA1") for faster, more reliable results than a natural language prompt.
• query_opentarget accepts direct GraphQL via query + variables parameters for precise queries. Natural language prompts work for discovery but GraphQL is more reliable for specific target-disease pairs.
• query_synapse datasets may be access-restricted — if results show access_restricted: true, the dataset requires approval through the Synapse web interface and cannot be retrieved programmatically.
• Identifier formats differ across databases:
  • UniProt uses accession IDs: P38398, Q9Y6K9
  • Ensembl uses gene IDs: ENSG00000012048
  • Open Targets uses Ensembl gene IDs (NOT HGNC symbols) — convert first via query_ensembl
  • gnomAD works best with HGNC gene symbols: BRCA1, TP53
  • ClinVar accepts gene names, variant descriptions, or RS IDs
• All prompt-based tools accept natural language but give better results with specificity: include organism ("human"), identifier type, and what information you need.
• Rate limits may apply on some databases — if you get 429 errors, space queries or reduce max_results.
• Large result sets for highly-studied genes (TP53, BRCA1, EGFR) — gnomAD and cBioPortal may return overwhelming responses. Always set max_results and use specific queries rather than broad gene-level searches.