Provides access to the Open Targets Platform GraphQL API for querying comprehensive target-disease associations, drug discovery data, and executing batch queries with entity search capabilities across targets, diseases, drugs, variants, and studies.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Open Targets Platform MCP search for genes associated with Alzheimer's disease"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
⚠️ DISCLAIMER: This project is currently experimental and under active development. Features, APIs, and documentation may change without notice ⚠️
Model Context Protocol (MCP) server for the Open Targets Platform API
This package is the official Open Targets Platform MCP server implementation that enables AI assistants to interact with the Open Targets Platform GraphQL API, a comprehensive resource for target-disease associations and drug discovery data.
Related MCP server: mcp-graphql-tools
🔍 Category-Based Schema Access: Fetch and explore focused subsets of the Open Targets Platform GraphQL schema using category-based subschemas
🚀 Pre-fetched Schema Optimization: The GraphQL schema is pre-fetched and cached at server startup to ensure immediate availability for tools
📊 Query Execution: Execute custom GraphQL queries against the Open Targets Platform API
⚡ Batch Query Processing: Execute the same query multiple times with different parameters efficiently
🔎 Entity Search: Search for entities across multiple types (targets, diseases, drugs, variants, studies)
🛠️ CLI Tools: Easy-to-use command-line interface for starting the server
🎯 jq Filtering (Optional): Server-side JSON processing using jq to reduce token consumption and improve performance. See jq Filtering for details.
The easiest way to use Open Targets Platform MCP is through the hosted service provided by Open Targets infrastructure at https://mcp.platform.opentargets.org/mcp
The fastest way to get started is using uvx, which will automatically download and run the package directly from GitHub.
Examples:
# Start HTTP server bound to localhost:8000 (default)
uvx --from git+https://github.com/opentargets/open-targets-platform-mcp otp-mcp
# Get help
uvx --from git+https://github.com/opentargets/open-targets-platform-mcp otp-mcp --help
# With jq filtering enabled
uvx --from git+https://github.com/opentargets/open-targets-platform-mcp otp-mcp --jqYou can run the MCP server using the official Docker image:
# Pull the latest image
docker pull ghcr.io/opentargets/open-targets-platform-mcp
# Run as a daemon with HTTP transport
docker run -d \
-p 8000:8000 \
-e OTP_MCP_HTTP_HOST=0.0.0.0 \
ghcr.io/opentargets/open-targets-platform-mcp
# Run as a daemon with jq filtering enabled
docker run -d \
-p 8000:8000 \
-e OTP_MCP_HTTP_HOST=0.0.0.0 \
-e OTP_MCP_JQ_ENABLED=true \
ghcr.io/opentargets/open-targets-platform-mcpFor available CLI arguments and environment variables, see the Server Settings table.
Both advanced deployment options require cloning the repository and setting up the virtual environment first:
# Clone the repository
git clone https://github.com/opentargets/open-targets-platform-mcp.git
cd open-targets-platform-mcp
# Install dependencies
uv sync --python 3.10For advanced usage and to utilize all FastMCP options, you can use the FastMCP CLI directly with the server module:
# Run using FastMCP CLI
uv run fastmcp run ./src/open_targets_platform_mcp/server.pyNote: For all FastMCP CLI options, see the FastMCP documentation.
Note: Use environment variables (see Server Settings table) to configure the server when using FastMCP CLI.
For development or to modify the codebase:
# Run the server
uv run otp-mcp
# Get help
uv run otp-mcp --helpThe package provides two command variants:
otp-mcp: Shorter alias (recommended)
open-targets-platform-mcp: Full command name
Both commands are functionally identical.
Configure the server using environment variables (all prefixed with OTP_MCP_). The following table shows all available configuration options:
Environment Variable | CLI Option | Description | Default |
|
| Open Targets Platform API endpoint URL |
|
|
| Server name displayed in MCP |
|
|
| Transport type: |
|
|
| HTTP server host (only used with |
|
|
| HTTP server port (only used with |
|
|
| Enable stateless HTTP mode (only used with |
|
|
| Request timeout in seconds for API calls |
|
|
| Enable jq filtering support |
|
|
| Enable rate limiting |
|
| (env only) | Maximum requests per second when rate limiting is enabled |
|
| (env only) | Maximum burst capacity when rate limiting is enabled |
|
|
| Enable logging of detailed timing information for requests |
|
Examples:
Using environment variables:
export OTP_MCP_TRANSPORT=stdio
export OTP_MCP_JQ_ENABLED=true
otp-mcpUsing CLI options:
otp-mcp --transport stdio --jqNote: CLI options take precedence over environment variables when both are provided.
The MCP server provides the following tools:
get_open_targets_graphql_schema: Fetch category-based subschemas from the Open Targets Platform API, including detailed documentation for relevant types and fields
get_type_dependencies: Explore schema type relationships by fetching the exact GraphQL SDL (Schema Definition Language) subset for specified types and all their recursively reachable dependencies
query_open_targets_graphql: Execute GraphQL queries to retrieve data about targets, diseases, drugs, and their associations
batch_query_open_targets_graphql: Execute the same GraphQL query multiple times with different variable sets for efficient batch processing
search_entities: Search for entities across multiple types (targets, diseases, drugs, variants, studies) and retrieve their standardized IDs
The MCP server implements a 3-step workflow that guides the LLM to efficiently retrieve data from the Open Targets Platform:
The LLM calls get_open_targets_graphql_schema with specific categories (e.g., "targets", "drug-mechanisms") to retrieve a focused subset of the schema. This provides detailed documentation for relevant types and fields, enabling the LLM to construct valid queries without being overwhelmed by the entire schema. The schema also includes specific guidance on how to properly declare GraphQL variables to avoid variable resolution errors.
If deeper or more specific schema exploration is needed, the LLM can fall back to the get_type_dependencies tool to fetch the exact dependency tree and SDL subset for one or more specific types.
Key entity types include:
Targets/Genes: Use ENSEMBL IDs (e.g., ENSG00000139618 for BRCA2)
Diseases: Use EFO/MONDO IDs (e.g., MONDO_0007254 for breast cancer)
Drugs: Use ChEMBL IDs (e.g., CHEMBL1201583 for aspirin)
Variants: Use "chr_pos_ref_alt" format or rsIDs
When a user query contains common names (gene symbols, disease names, drug names), the LLM uses search_entities to convert them to standardized IDs required by the API.
The LLM constructs and executes GraphQL queries using:
Standardized IDs from Step 2
Query structure from the schema
jq filters (optional, when enabled) to extract only requested fields, minimizing token consumption
Tool selection:
query_open_targets_graphql for single queries
batch_query_open_targets_graphql for multiple identical queries with different parameters (reduces latency and tokens)
The MCP server supports optional server-side JSON processing using jq expressions. This feature is disabled by default but can be enabled if you want to reduce token consumption.
You want to reduce token consumption by extracting only specific fields from API responses
Working with large API responses where only a subset of data is needed
The calling LLM is proficient at tool calling and can reliably construct jq filters
Simplicity is preferred over optimization
Working with straightforward queries that don't benefit from filtering
The LLM should receive complete API responses
When jq filtering is enabled, the query tools expose a jq_filter parameter. The jq filter is applied server-side before the response is returned, extracting only the relevant data and discarding unnecessary fields.
Example: To extract only the gene symbol and ID from a target query:
jq_filter: ".data.target | {id, symbol: .approvedSymbol}"This significantly reduces token consumption by returning only the requested fields instead of the full API response.
For detailed instructions on configuring the Open Targets Platform MCP server with Claude Desktop, including both remote hosted service and local installation configurations, see CLAUDE_DESKTOP.md.
The test suite is built around two guiding principles:
1. Test at the highest meaningful level.
Tests exercise the server through the fastmcp in-process client (Client.call_tool()), the same interface an LLM uses at runtime. This makes every test a near-system test: tool registration, argument validation, description generation, and response serialisation are all covered as a single end-to-end path, rather than testing internal functions in isolation.
2. Use GraphQL replay instead of live network calls.
Real API responses are recorded once into a cassette file (test/fixtures/generated/graphql_cassette.json) by running the generator script against the live API. During normal test runs the cassette is replayed deterministically, so tests are fast, reproducible, and do not depend on network availability. The cassette is regenerated intentionally when new queries are needed:
uv run python test/fixtures/generated/generate_fixtures.pyTo run tests against the live API instead of the cassette:
uv run python -m pytest --liveContributions are welcome! Please open an issue or submit a pull request on the GitHub repository.
This project is licensed under the terms of the license specified in LICENSE.
Execute the same GraphQL query multiple times with different variable sets.
Use this tool instead of the regular query tool when you need to run the same query repeatedly with different arguments (e.g., querying multiple drugs, targets, or diseases).
WORKFLOW - Follow these steps in order:
Step 1: RESOLVE IDENTIFIERS
If user provides common names (gene symbols, disease names, drug names),
use search_entity tool FIRST to convert them to standardized IDs:
- Targets/Genes: "BRCA1", "BRCA2" -> ENSEMBL IDs "ENSG00000012048", "ENSG00000139618"
- Diseases: "breast cancer" -> EFO/MONDO ID "MONDO_0007254"
- Drugs: "aspirin", "ibuprofen" -> ChEMBL IDs "CHEMBL1201583", "CHEMBL521"
- Variants: Use "chr_pos_ref_alt" format or rsIDs
Example: search_entity(query_string="BRCA1 BRCA2", entity_names=["target"])Step 2: LEARN QUERY STRUCTURE
Call get_open_targets_graphql_schema with relevant categories to retrieve
the schema subset needed for your query. Select categories that cover the
data domains you need - BE INCLUSIVE (it's better to include extra categories
than to miss required types).
Example: For a query about drug mechanisms and safety:
get_open_targets_graphql_schema(categories=["drug-mechanisms", "drug-safety"])
Study the returned schema to understand available types, fields, and their
relationships, then construct a GraphQL query that fetches the information
the user needs.
FALLBACK: If you encounter errors or need detailed information about specific
types, use `get_type_dependencies` sparingly to explore type relationships.
This tool provides exhaustive type dependency information but should only be
used when category-based retrieval is insufficient.Step 3: CONSTRUCT AND EXECUTE BATCH QUERY Build GraphQL query and variables_list using: - Standardized IDs from Step 1 (REQUIRED) - Query patterns from Step 2 - Follow the "COMMON MISTAKES TO AVOID" guidance in the schema output
Call this tool with query_string, variables_list, and key_field.REQUIRED IDENTIFIER FORMATS:
Targets/Genes: ENSEMBL IDs (e.g., "ENSG00000139618")
Diseases: EFO IDs (e.g., "EFO_0000305") or MONDO IDs (e.g., "MONDO_0007254")
Drugs: ChEMBL IDs (e.g., "CHEMBL1201583")
Variants: "chr_pos_ref_alt" format (e.g., "19_44908822_C_T") or rsIDs (e.g., "rs7412")
Studies: Study IDs (e.g., "GCST90002357")
Credible Sets: Study Locus IDs (e.g., "7d68cc9c70351c9dbd2a2c0c145e555d")
Args: query_string (str): The GraphQL query string to execute for all variable sets. variables_list (list[dict[str, Any]]): List of variable dictionaries, one per query execution. key_field (str): Variable field name to use as key in results mapping.
Returns: (BatchQueryResult): Results keyed by the specified field value, with execution summary.
| Name | Required | Description | Default |
|---|---|---|---|
| key_field | Yes | Variable field name to use as key in results mapping. | |
| query_string | Yes | The GraphQL query string to execute for all variable sets. | |
| variables_list | Yes | List of variable dictionaries, one per query execution. |
| Name | Required | Description |
|---|---|---|
| results | Yes | |
| status_counts | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true, so the safety profile is already established. The description adds meaningful behavioral context: it reveals that one query_string is executed for all variable sets, that results are keyed by the specified field value, and that an execution summary is returned. This goes beyond the bare read-only annotation without contradicting it, though it does not mention rate limits, concurrency, or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured with marked steps, bullet lists, and examples. It front-loads the purpose and then organizes prerequisite actions logically. It earns its length given the tool's complexity, though the Args section repeats schema descriptions and the workflow could be slightly tightened without losing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a complex orchestration tool, and the description covers the full workflow: identifier resolution, schema retrieval, fallback dependency exploration, query construction, and execution. It lists required identifier formats and references common-mistakes guidance from the schema output. Since an output schema exists, return value details are already covered externally. An agent has everything needed to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds significant value beyond the schema by specifying required identifier formats (ENSEMBL, ChEMBL, MONDO, rsIDs, chr_pos_ref_alt) and giving usage examples with search_entity. It also clarifies the role of key_field as the mapping key for results, which is more concrete than the schema's brief description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence states a specific verb/resource: 'Execute the same GraphQL query multiple times with different variable sets.' It clearly differentiates from the 'regular query tool' by naming the condition (repeated execution with different arguments). The batch behavior is unambiguous and distinct from siblings like query_open_targets_graphql.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this tool instead of the regular query tool when you need to run the same query repeatedly with different arguments.' It goes further with a step-by-step workflow, telling when to use search_entity, get_open_targets_graphql_schema, and get_type_dependencies as a fallback. This is exactly the kind of when/when-not/alternatives guidance that helps an agent decide correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve the Open Targets Platform GraphQL schema filtered by category.
You MUST specify one or more categories to retrieve the relevant schema subset. Categories group related GraphQL types into coherent subschemas (e.g., 'drug-mechanisms', 'genetic-associations', 'target-safety').
The returned schema includes types from the specified categories plus their dependencies expanded.
Available categories:
cancer-genomics: Cancer-specific genomic evidence from Cancer Gene Census, IntOGen, cancer biomarkers databases, and cancer hallmarks. Identifies cancer driver genes and somatic mutations.
clinical-genetics: Clinical genetics databases and rare disease evidence from ClinGen, ClinVar, Genomics England PanelApp, Orphanet, and Gene2Phenotype. Provides clinical validity of gene-disease relationships, pathogenic variants, and clinical genomics panels.
comparative-genomics: Cross-species comparative genomics and orthology relationships for leveraging model organism data. Shows evolutionary conservation and functional predictions based on homology.
disease-associations: Target-disease association evidence and target prioritisation, integrating evidence across multiple data types. Shows the strength of association between genes/targets and diseases and the target prioritisation factors that can be used to prioritise targets for further investigation.
disease-phenotypes: Disease phenotypes, symptoms, and ontology for understanding clinical manifestations, disease classifications, and relationships between different conditions.
drug-indications: Approved and investigational drug indications, clinical trial phases, mechanism-based predictions for drug repurposing, and known drug-disease relationships.
drug-mechanisms: Drug mechanisms of action and target interactions from ChEMBL, including drug-target relationships, polypharmacology profiles, and molecular mechanisms of therapeutic effects.
drug-safety: Post-market drug safety and pharmacovigilance data from FDA FAERS, including adverse events, drug warnings, and safety alerts for approved medications.
entity-search: Cross-entity search and entity discovery across all entity types with keyword search capabilities. Enables finding targets, diseases, drugs, variants, and studies by name or identifier.
experimental-models: Experimental model organism data including CRISPR knockout screens, mouse phenotypes from IMPC, cancer cell line dependency from DepMap, and chemical probes. Provides functional validation data from laboratory experiments.
functional-genomics: Gene expression, biological pathways, and systems biology data from Expression Atlas, Reactome, Gene Ontology. Provides context on gene function, regulation, and pathway involvement.
genetic-associations: Genome-wide association studies (GWAS) and molecular QTL associations. Returns GWAS summary statistics, shared trait studies, and disease-associated genetic variants from population-scale studies. Fine-mapping results and credible set analysis from GWAS and QTL studies. Includes locus-to-gene predictions, colocalization analyses, and probabilistic identification of causal variants.
genetic-constraint: Genetic constraint metrics. Measures selection pressure on genes including loss-of-function intolerance, showing which genes are essential for survival.
literature-evidence: Scientific literature and bibliographic data, including disease and drug bibliographies. Supports text-mined evidence and citation networks.
molecular-interactions: Protein-protein interactions and molecular networks for understanding biological context, cellular pathways, and functional relationships between biomolecules.
pharmacogenomics: Genetic variation affecting drug response, including gene-drug interactions, genotype-dependent efficacy or toxicity, and personalized medicine applications.
platform-metadata: Platform metadata including version information, data release prefix, and metadata on all downloadable datasets. Also includes metadata on Open Targets (OTAR) projects (if available).
protein-information: Protein abundances and subcellular localization data.
target-safety: Target safety liabilities and toxicity predictions based on adverse events, animal toxicology, and clinical safety flags. Assesses potential risks of modulating a therapeutic target.
target-tractability: Target druggability and tractability assessments, including small molecule and antibody tractability predictions. Evaluates the likelihood of successfully developing drugs against a target.
variant-annotation: Variant functional annotation and population genetics. Includes variant effect predictions (VEP), European Variation Archive data, UniProt variant annotations, and predicted functional consequences of genetic variation.
Args: categories (list[str]): List of category names to filter the schema. Returns only types relevant to the specified categories. (examples: ['drug-mechanisms'], ['target-safety', 'drug-safety'])
Returns: (str): The schema text in SDL (Schema Definition Language) format.
| Name | Required | Description | Default |
|---|---|---|---|
| categories | Yes | List of category names to filter the schema. Returns only types relevant to the specified categories. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safe read-only nature is covered. The description adds valuable behavioral context by explaining that returned schema includes 'types from the specified categories plus their dependencies expanded' and that the return is SDL text. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long due to the category list, but each category entry is a single informative sentence with data sources and purpose. The 'Available categories', 'Args', and 'Returns' sections provide clear structure)Skip no dead weight.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Coverage is strong: required category argument, full category enumeration, dependency-expansion behavior, and return format are all described. The description does not discuss error handling for invalid categories, but given the output schema and annotations, this is a minor omission.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of the parameter description, but the description goes well beyond it by enumerating all 20 category values with detailed, purpose-specific explanations. It also provides concrete usage examples in the Args section, giving an agent clear understanding of what each category yields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence states a specific verb ('Retrieve') and resource ('Open Targets Platform GraphQL schema') with a clear modifier ('filtered by category'). This unambiguously distinguishes it from sibling tools like get_type_dependencies, which concerns dependencies rather than schema retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'You MUST specify one or more categories' and provides a comprehensive list of available categories, making it clear how to invoke the tool. It does not explicitly contrast against alternatives like query_open_targets_graphql, but the usage context is otherwise clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get schema subsets for types, separated by specific and shared deps.
Given a list of type names, returns SDL (Schema Definition Language) organized into type-specific dependencies and shared dependencies.
Args: type_names (list[str]): List of GraphQL type names to start exploration from. (examples: ['Target', 'Drug'])
Returns: (dict[str, str]): Dictionary with one key per input type: SDL for types ONLY reachable from that type and 'shared' key: SDL for types reachable from multiple input types.
| Name | Required | Description | Default |
|---|---|---|---|
| type_names | Yes | List of GraphQL type names to start exploration from. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already indicates a safe, read-only operation. The description adds meaningful behavioral context by detailing the return structure (dict with per-type keys and a 'shared' key) and specifying that SDL is returned only for reachable types. It does not contradict annotations and enriches understanding of the tool's behavior beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear one-line purpose followed by Args and Returns sections. It is front-loaded with the core idea, and the example is useful. There is some redundancy (Args duplicates the schema description), but overall it is concise and organized without unnecessary fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for an agent to invoke the tool correctly: it explains the input, output format, and provides an example. The presence of an output schema further reduces the need to describe return types. It does not cover edge cases like missing type names, but given the read-only nature and clear contract, this is a minor omission.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% since the schema already describes type_names as 'List of GraphQL type names to start exploration from.' The description repeats this and adds an example (['Target', 'Drug']), which is helpful but does not add significant new meaning beyond the schema. The baseline of 3 is appropriate because the schema does the heavy lifting, and the example adds marginal value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves schema subsets for given types, separating specific and shared dependencies. It uses a specific verb ('Get') and resource ('schema subsets for types'). While it doesn't explicitly distinguish itself from sibling tools, the purpose is unambiguous and the output format is described, making it easy for an agent to understand what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context ('Given a list of type names, returns SDL...') but does not explicitly state when to use this tool versus alternatives like query_open_targets_graphql or get_open_targets_graphql_schema. There is no mention of when not to use it or what makes it the preferred choice. The example usage provides some implicit guidance, but exclusions and selection criteria are missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute GraphQL queries against the Open Targets Platform API.
WORKFLOW - Follow these steps in order:
Step 1: RESOLVE IDENTIFIERS
If user provides common names (gene symbols, disease names, drug names),
use search_entity tool FIRST to convert them to standardized IDs:
- Targets/Genes: "BRCA2" -> ENSEMBL ID "ENSG00000139618"
- Diseases: "breast cancer" -> EFO/MONDO ID "MONDO_0007254"
- Drugs: "aspirin" -> ChEMBL ID "CHEMBL1201583"
- Variants: Use "chr_pos_ref_alt" format or rsIDs
Example: search_entity(query_string="BRCA2", entity_names=["target"])Step 2: LEARN QUERY STRUCTURE
Call get_open_targets_graphql_schema with relevant categories to retrieve
the schema subset needed for your query. Select categories that cover the
data domains you need - BE INCLUSIVE (it's better to include extra categories
than to miss required types).
Example: For a query about drug mechanisms and safety:
get_open_targets_graphql_schema(categories=["drug-mechanisms", "drug-safety"])
Study the returned schema to understand available types, fields, and their
relationships, then construct a GraphQL query that fetches the information
the user needs.
FALLBACK: If you encounter errors or need detailed information about specific
types, use `get_type_dependencies` sparingly to explore type relationships.
This tool provides exhaustive type dependency information but should only be
used when category-based retrieval is insufficient.Step 3: CONSTRUCT AND EXECUTE QUERY Build GraphQL query using: - Standardized IDs from Step 1 (REQUIRED) - Query structure from Step 2 - Follow the "COMMON MISTAKES TO AVOID" guidance in the schema output
Call this tool with query_string and optional variables.REQUIRED IDENTIFIER FORMATS:
Targets/Genes: ENSEMBL IDs (e.g., "ENSG00000139618")
Diseases: EFO IDs (e.g., "EFO_0000305") or MONDO IDs (e.g., "MONDO_0007254")
Drugs: ChEMBL IDs (e.g., "CHEMBL1201583")
Variants: "chr_pos_ref_alt" format (e.g., "19_44908822_C_T") or rsIDs (e.g., "rs7412")
Studies: Study IDs (e.g., "GCST90002357")
Credible Sets: Study Locus IDs (e.g., "7d68cc9c70351c9dbd2a2c0c145e555d")
Args: query_string (str): GraphQL query string starting with 'query' keyword. variables (UnionType[dict[str, Any], None]): Optional dict or JSON string with query variables.
Returns: (QueryResult): GraphQL response with data field containing targets, diseases, drugs, variants, studies or error message.
| Name | Required | Description | Default |
|---|---|---|---|
| variables | No | Optional dict or JSON string with query variables. | |
| query_string | Yes | GraphQL query string starting with 'query' keyword. |
| Name | Required | Description |
|---|---|---|
| data | No | The data returned by the query. Data could still be available even if the status is not success and it MUST be treated with caution as it may be INCOMPLETE or UNRELIABLE. |
| status | Yes | The status of the query result. |
| message | No | The message associated with the query result. This field is typically used to provide additional information about the non-successful query result, such as error details or warnings. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, and the description is consistent with that. It adds useful behavioral context beyond the annotation: required identifier formats, the necessity of building queries from the fetched schema, and the shape of the return value. No contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured with numbered workflow steps, clear headers, and a separate section for required identifier formats. It is front-loaded with the core action. Some redundancy exists in the Args/Returns section, which mirrors the schema, but the overall structure earns its length for a complex GraphQL tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, the presence of an output schema, and readOnlyHint annotation, the description is very complete. It covers the full workflow, fallback strategies, required ID formats, query construction guidance, and expected return shape. No material information an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3, but the description adds real value by requiring standardized IDs, enumerating the exact ID formats per entity type, and mandating that the query string start with 'query'. This goes beyond the schema's terse property descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Execute GraphQL queries against the Open Targets Platform API.' It clearly states what the tool does and includes a detailed workflow, but it does not explicitly distinguish this tool from the sibling batch_query_open_targets_graphql, so the differentiation is left implicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a strong sequential workflow: resolve identifiers with a search tool, learn query structure via get_open_targets_graphql_schema, use get_type_dependencies as fallback, then call this tool. However, it refers to 'search_entity' while the actual sibling is 'search_entities', and it never explains when to choose this tool over batch_query_open_targets_graphql.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for entities across multiple types using the Open Targets Platform search API.
This tool performs a streamlined entity search that returns the id and entity type for up to 3 matching entities across targets, diseases, drugs, variants, and studies.
Supports multiple query strings in a single call - each query is executed independently and results are returned in a dictionary keyed by the query string.
Args: query_strings (list[str]): List of search queries. (examples: ['BRCA1', 'aspirin'])
Returns: (dict[str, list[SearchEntitiesFoundEntity]]): Top 3 hits for each query string, with entity ID and type.
| Name | Required | Description | Default |
|---|---|---|---|
| query_strings | Yes | List of search queries. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already covers the safety profile, and the description adds meaningful behavior beyond it: the 'up to 3' result limit, that each query executes independently, and that results are keyed by query string. It also states the entity-type scope. This is valuable behavioral context that annotations alone do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded in the first sentence, followed by result behavior, multi-query support, and structured Args/Returns sections. It is efficient and each sentence earns its place, though the Args and Returns sections partially restate what the schema and output schema already declare.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter, read-only tool with an output schema present, the description is complete: it covers purpose, entity scope, result limit, multi-query behavior, and return shape. Nothing essential for correct invocation is missing; the only minor gap is lack of explicit alternative routing, which the sibling names make obvious.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (query_strings documented with examples and minItems), so the baseline is 3. The description adds value beyond the schema by clarifying multi-query semantics — that queries run independently and results are returned in a dictionary keyed by the query string — which the schema does not convey. The Args section repeats the schema example but the behavioral explanation compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Search for entities... using the Open Targets Platform search API') and names the entity types covered (targets, diseases, drugs, variants, studies). It clearly differentiates itself from the GraphQL-focused siblings (query/batch_query/get_schema) by being a distinct search-API surface, so an agent can tell it apart without opening the sibling schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys its role as a 'streamlined entity search' and the sibling tools are visibly different (GraphQL query/schema tools), implying when it should be used. However, it never explicitly states exclusions or names alternatives — e.g., it does not say 'for complex GraphQL queries use query_open_targets_graphql instead.' The usage context is implied, not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0batch_query_open_targets_graphqlget_open_targets_graphql_schemaget_type_dependenciesquery_open_targets_graphqlsearch_entitiesScored across 5 tools
The two schema-discovery tools (get_open_targets_graphql_schema and get_type_dependencies) overlap somewhat, but their category-based versus type-based approaches are clearly described. The search, query, and batch-query tools have distinct purposes and are unlikely to be confused.
Tool names are consistently snake_case and mostly verb-first, but the convention mixes get_, search_, query_, and batch_query_ prefixes, and the long open_targets_graphql descriptor appears inconsistently. The docs also reference search_entity while the actual tool is search_entities.
Five tools is well-scoped for a read-only GraphQL data platform: schema discovery, type dependency exploration, entity search, single query execution, and batch query execution each serve a necessary role without redundancy or bloat.
The toolset covers the full workflow: search to resolve identifiers, schema introspection to learn query structure, single-query execution, and batch execution for repeated queries. There are no obvious missing operations for the stated purpose of interacting with the Open Targets Platform API.
Open Targets MCP — disease/target/drug knowledge graph.
Connect AI clients to biomedical data and tools.
Query your OpsLevel internal developer portal: catalog, maturity data, and tech docs.
Cited gene, variant (rsID) and CPIC drug–gene lookups for AI agents. Read-only, no key.
