ensembl-mcp-server

List Ensembl Species

ensembl_list_species

Read-onlyIdempotent

List species supported by Ensembl with display name, common name, assembly, taxon ID, and division. Required discovery step — species names like homo_sapiens are opaque to non-biologists and are the input format every other Ensembl tool expects. Use nameContains to find a species by partial name match; filter by division to select one. With no division, lists the endpoint default division — the vertebrates (~356 species on the default GRCh38 endpoint). Species are sorted by internal name and returned max_results at a time (default 50); totalCount reports every match, and when more follow, nextOffset is the offset for the next page.

Input Schema

Name	Required	Description
`offset`	No	0-based position in the name-sorted matches where the returned page starts. Default 0. Pass nextOffset from a previous response to fetch the following page; an offset at or past totalCount returns no species.
`division`	No	Filter to a specific Ensembl division. EnsemblVertebrates includes human, mouse, zebrafish, and other vertebrates. EnsemblPlants covers crop and model plant genomes. EnsemblFungi, EnsemblMetazoa, EnsemblProtists cover non-vertebrate model organisms. Omit to return the endpoint default division (vertebrates).
`max_results`	No	Maximum number of species to return, counted from offset. Default 50. Set to 0 to return every matching species from offset to the end, uncapped. totalCount always reports the full number of matches before this cap.
`nameContains`	No	Case-insensitive substring filter applied locally after fetching. Matches against species name, display name, and common name. Example: "sapiens" matches homo_sapiens; "mouse" matches mus_musculus.

Output Schema

Name	Required	Description
`cap`	No	The max_results limit applied to this page.
`error`	No	Present when the call failed. Absent on success.
`shown`	No	Number of species returned on this page.
`notice`	No	Guidance when the filter matches no species, the offset is past the end, or more species follow this page.
`species`	No	Species matching the filter criteria, sorted by internal name: at most max_results entries starting at offset.
`truncated`	No	True when more matching species follow this page; request nextOffset to continue.
`nextOffset`	No	Offset of the first species after this page — pass it as offset to fetch the next page. Present only when more species follow.
`totalCount`	No	Total number of matching species after local filtering, before offset and max_results. Exceeds the returned species count when the list was paged.

Schema Changelog

Changes observed during successful MCP inspections.

Changed9 schema fields changedOct 13, 2026

addedInput schema / properties / max_results

Added value: +{
+  "default": 50,
+  "description": "Maximum number of species to return, counted from offset. Default 50. Set to 0 to return every matching species from offset to the end, uncapped. totalCount always reports the full number of matches before this cap.",
+  "maximum": 9007199254740991,
+  "minimum": 0,
+  "type": "integer"
+}

addedInput schema / properties / offset

Added value: +{
+  "default": 0,
+  "description": "0-based position in the name-sorted matches where the returned page starts. Default 0. Pass nextOffset from a previous response to fetch the following page; an offset at or past totalCount returns no species.",
+  "maximum": 9007199254740991,
+  "minimum": 0,
+  "type": "integer"
+}

addedOutput schema / properties / cap

Added value: +{
+  "description": "The max_results limit applied to this page.",
+  "type": "number"
+}

addedOutput schema / properties / nextOffset

Added value: +{
+  "description": "Offset of the first species after this page — pass it as offset to fetch the next page. Present only when more species follow.",
+  "type": "number"
+}

changedOutput schema / properties / notice / description

Previous value: -"Guidance when the filter matches no species."New value: +"Guidance when the filter matches no species, the offset is past the end, or more species follow this page."

addedOutput schema / properties / shown

Added value: +{
+  "description": "Number of species returned on this page.",
+  "type": "number"
+}

changedOutput schema / properties / species / description

Previous value: -"Species matching the filter criteria, sorted by internal name."New value: +"Species matching the filter criteria, sorted by internal name: at most max_results entries starting at offset."

changedOutput schema / properties / totalCount / description

Previous value: -"Total number of matching species after local filtering."New value: +"Total number of matching species after local filtering, before offset and max_results. Exceeds the returned species count when the list was paged."

addedOutput schema / properties / truncated

Added value: +{
+  "description": "True when more matching species follow this page; request nextOffset to continue.",
+  "type": "boolean"
+}

Changed6 schema fields changedAug 22, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "species",
+      "totalCount"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode.",
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

removedOutput schema / required

Removed value: -[
-  "species",
-  "totalCount"
-]

Changed1 schema field changedJul 3, 2026

changedInput schema / properties / division / description

Previous value: -"Filter to a specific Ensembl division. EnsemblVertebrates includes human, mouse, zebrafish, and other vertebrates. EnsemblPlants covers crop and model plant genomes. EnsemblFungi, EnsemblMetazoa, EnsemblProtists cover non-vertebrate model organisms. Omit to return all divisions."New value: +"Filter to a specific Ensembl division. EnsemblVertebrates includes human, mouse, zebrafish, and other vertebrates. EnsemblPlants covers crop and model plant genomes. EnsemblFungi, EnsemblMetazoa, EnsemblProtists cover non-vertebrate model organisms. Omit to return the endpoint default division (vertebrates)."

First observedJun 7, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations already declare readOnlyHint, openWorldHint, and idempotentHint, but the description adds important behavioral detail: species are sorted by internal name, results are paginated with max_results defaulting to 50, totalCount reports the full match count, and nextOffset gives the next page position. It also discloses the default division and approximate species count, which helps the agent anticipate result scope.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the purpose and required discovery-step rationale, then moves through filtering and pagination. It is dense and mostly earns its place, though the opening enumeration of returned fields partially duplicates information available in the output schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given an output schema, the description need not explain return structure, and it does not overreach there. It covers the tool's purpose, discovery role, filtering options, default behavior, sorting, pagination, and result counts, leaving no meaningful gap for an agent deciding how to call it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so each parameter is already well documented in the input schema. The description reinforces nameContains, division, and pagination usage, but adds little parameter-specific meaning beyond what the schema already provides, only marginally deepening the default-division context with the ~356 vertebrate count.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: list species supported by Ensembl, including the fields returned. It also explicitly frames the tool as the required discovery step whose output format every other Ensembl sibling expects, making it easy to distinguish from tools that operate on genes, regions, or sequences.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It tells the agent when to use the tool: as the required discovery step before other Ensembl tools. It also explains the two filtering routes, nameContains for partial-name search and division for selecting a specific Ensembl division, and notes the default division when neither is used.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All ensembl-mcp-server tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.