ensembl-mcp-server

Get Sequence

ensembl_get_sequence

Read-onlyIdempotent

Fetch the DNA, cDNA, CDS, or protein sequence for a gene, transcript, protein, or genomic region. Returns a window of the sequence — the first 10,000 characters by default — with its stable ID, molecule type, and full length. When more follows the window, truncated is true and nextOffset is the offset to request next; walking nextOffset reconstructs the whole sequence, and max_length 0 returns everything from offset to the end. The type parameter selects which sequence is fetched: genomic (default, includes introns), cdna (spliced transcript), cds (coding sequence only), protein. For region mode, set id to a region — either species:chr:start-end (e.g. homo_sapiens:13:32315086-32400268) or a bare chr:start-end with species set (e.g. id 13:32315086-32400268, species homo_sapiens), spanning at most 10,000,000 bases; a :-1 suffix (13:32315086-32315100:-1) returns the reverse-strand sequence. Regions return genomic DNA only. Protein sequences require a transcript or protein stable ID (ENST…/ENSP…), not a gene ID — use ensembl_lookup_gene and its canonicalTranscript field first; expand_transcripts=true also supplies transcript biotypes and MANE Select accessions.

Input Schema

Name	Required	Description	Default
`id`	Yes	Ensembl stable ID (ENSG…, ENST…, ENSP…) or a genomic region for region mode — an id containing a colon is a region. A version suffix on a stable ID (ENST00000380152.8) is dropped before the request. Region accepts species:chr:start-end (e.g. homo_sapiens:13:32315086-32400268) or a bare chr:start-end (e.g. 13:32315086-32400268) when the species field is set. Coordinates are whole numbers; start..end works as well as start-end, and a :1 or :-1 suffix picks the strand (13:32315086-32315100:-1 returns the reverse complement). A region needs start at or below end, within the sequence region, and spans at most 10,000,000 bases. Name chromosomes as Ensembl does (13, X, MT; chr13 also works); the mitochondrion is MT in vertebrates, mitochondrion_genome in Drosophila, and MtDNA in C. elegans. M and chrM are accepted only where Ensembl resolves them to the mitochondrion (Drosophila, for one); elsewhere they fail as invalid_region naming the mitochondrion of the species.
`type`	No	Sequence type to retrieve. genomic: full genomic DNA including introns (default). cdna: spliced transcript sequence (requires ENST… ID). cds: coding sequence only, no UTRs (requires ENST… ID with coding transcript). protein: amino acid sequence (requires ENST… or ENSP… ID). Region ids are genomic-only — request cdna, cds, or protein from a transcript or protein stable ID. A protein ID (ENSP…) serves only its protein; a non-coding transcript has no protein or cds.	genomic
`offset`	No	0-based character offset where the returned window starts, counted in the resolved sequence (including any expand_5prime/expand_3prime flank). Default 0. Pass nextOffset from a truncated response to fetch the following window; an offset at or past the end returns an empty window.
`species`	No	Species in Ensembl internal format (e.g. homo_sapiens). Required for a bare chr:start-end region. For the species:chr:start-end form the species in id takes precedence and this field is ignored. Unused for stable ID lookups — Ensembl infers species from the ID prefix.
`max_length`	No	Maximum number of characters in the returned window. Default 10000. Set to 0 to return everything from offset to the end, uncapped.
`expand_3prime`	No	Number of base pairs to extend downstream (3' direction) of the requested feature. Default 0. Only applies to genomic sequences and region queries; on a :-1 region it extends the lower coordinate.
`expand_5prime`	No	Number of base pairs to extend upstream (5' direction) of the requested feature. Default 0. Only applies to genomic sequences and region queries; on a :-1 region it extends the higher coordinate.

Output Schema

Name	Required	Description
`id`	No	The stable ID or region used for the lookup.
`seq`	No	The requested window of the sequence: at most max_length characters starting at offset. DNA sequences use IUPAC nucleotide codes (ACGT + ambiguity codes); protein sequences use single-letter amino acid codes. Empty when offset is at or past the end.
`type`	No	Sequence type returned (genomic, cdna, cds, or protein).
`error`	No	Present when the call failed. Absent on success.
`length`	No	Full sequence length in characters, not the window size — nucleotides for genomic/cdna/cds, amino-acid residues for protein. Includes any expand_5prime/expand_3prime flank.
`notice`	No	Guidance about the window: how to continue when truncated, or why it is empty when the offset is past the end.
`offset`	No	0-based character offset where this window starts.
`truncated`	No	True when more sequence follows this window; request nextOffset to continue.
`nextOffset`	No	Offset of the first character after this window — pass it as offset to fetch the next window. Present only when truncated.
`description`	No	Sequence description from Ensembl, if provided.

Schema Changelog

Changes observed during successful MCP inspections.

Changed7 schema fields changedOct 13, 2026

changedInput schema / properties / expand_3prime / description

Previous value: -"Number of base pairs to extend downstream (3' direction) of the requested feature. Default 0. Only applies to genomic sequences and region queries."New value: +"Number of base pairs to extend downstream (3' direction) of the requested feature. Default 0. Only applies to genomic sequences and region queries; on a :-1 region it extends the lower coordinate."

changedInput schema / properties / expand_5prime / description

Previous value: -"Number of base pairs to extend upstream (5' direction) of the requested feature. Default 0. Only applies to genomic sequences and region queries."New value: +"Number of base pairs to extend upstream (5' direction) of the requested feature. Default 0. Only applies to genomic sequences and region queries; on a :-1 region it extends the higher coordinate."

changedInput schema / properties / id / description

Previous value: -"Ensembl stable ID (ENSG…, ENST…, ENSP…) or a genomic region for region mode. Region accepts species:chr:start-end (e.g. homo_sapiens:13:32315086-32400268) or a bare chr:start-end (e.g. 13:32315086-32400268) when the species field is set. A region needs start at or below end, within the sequence region, and spans at most 10,000,000 bases."New value: +"Ensembl stable ID (ENSG…, ENST…, ENSP…) or a genomic region for region mode — an id containing a colon is a region. A version suffix on a stable ID (ENST00000380152.8) is dropped before the request. Region accepts species:chr:start-end (e.g. homo_sapiens:13:32315086-32400268) or a bare chr:start-end (e.g. 13:32315086-32400268) when the species field is set. Coordinates are whole numbers; start..end works as well as start-end, and a :1 or :-1 suffix picks the strand (13:32315086-32315100:-1 returns the reverse complement). A region needs start at or below end, within the sequence region, and spans at most 10,000,000 bases. Name chromosomes as Ensembl does (13, X, MT; chr13 also works); the mitochondrion is MT in vertebrates, mitochondrion_genome in Drosophila, and MtDNA in C. elegans. M and chrM are accepted only where Ensembl resolves them to the mitochondrion (Drosophila, for one); elsewhere they fail as invalid_region naming the mitochondrion of the species."

changedInput schema / properties / species / description

Previous value: -"Species in Ensembl internal format (e.g. homo_sapiens). Required for a bare chr:start-end region; optional for the species:chr:start-end form (the embedded species is used when the field is omitted). Optional for stable ID lookups — Ensembl infers species from the ID prefix."New value: +"Species in Ensembl internal format (e.g. homo_sapiens). Required for a bare chr:start-end region. For the species:chr:start-end form the species in id takes precedence and this field is ignored. Unused for stable ID lookups — Ensembl infers species from the ID prefix."

changedInput schema / properties / type / description

Previous value: -"Sequence type to retrieve. genomic: full genomic DNA including introns (default). cdna: spliced transcript sequence (requires ENST… ID). cds: coding sequence only, no UTRs (requires ENST… ID with coding transcript). protein: amino acid sequence (requires ENST… or ENSP… ID). Region ids are genomic-only — request cdna, cds, or protein from a transcript or protein stable ID."New value: +"Sequence type to retrieve. genomic: full genomic DNA including introns (default). cdna: spliced transcript sequence (requires ENST… ID). cds: coding sequence only, no UTRs (requires ENST… ID with coding transcript). protein: amino acid sequence (requires ENST… or ENSP… ID). Region ids are genomic-only — request cdna, cds, or protein from a transcript or protein stable ID. A protein ID (ENSP…) serves only its protein; a non-coding transcript has no protein or cds."

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `not_found`: The stable ID or region was not found in Ensembl. `type_mismatch`: A non-genomic type (cdna, cds, or protein) was requested for a region id or a gene ID. `missing_species`: A bare chr:start-end region was given without a species. `invalid_region`: A region id has its start after its end, starts past the end of its sequence region, spans more than the 10,000,000-base maximum, or names a sequence region the species lacks. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `not_found`: The stable ID or region was not found in Ensembl. `type_mismatch`: The requested type does not exist for the id: cdna, cds, or protein for a region id or a gene ID; genomic, cdna, or cds for a protein ID; or protein or cds for a non-coding transcript. `invalid_species`: The species of a region (the species field or the species prefix in id) was not recognized by Ensembl. `missing_species`: A bare chr:start-end region was given without a species. `invalid_region`: A region id is not in the [species:]chr:start-end form, has its start after its end, starts past the end of its sequence region, spans more than the 10,000,000-base maximum, names the mitochondrion M or chrM where Ensembl resolves that to another region or none, or names a sequence region the species lacks. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "not_found",
-  "type_mismatch",
-  "missing_species",
-  "invalid_region"
-]New value: +[
+  "not_found",
+  "type_mismatch",
+  "invalid_species",
+  "missing_species",
+  "invalid_region"
+]

Changed14 schema fields changedSep 24, 2026

changedInput schema / properties / id / description

Previous value: -"Ensembl stable ID (ENSG…, ENST…, ENSP…) or a genomic region for region mode. Region accepts species:chr:start-end (e.g. homo_sapiens:13:32315086-32400268) or a bare chr:start-end (e.g. 13:32315086-32400268) when the species field is set."New value: +"Ensembl stable ID (ENSG…, ENST…, ENSP…) or a genomic region for region mode. Region accepts species:chr:start-end (e.g. homo_sapiens:13:32315086-32400268) or a bare chr:start-end (e.g. 13:32315086-32400268) when the species field is set. A region needs start at or below end, within the sequence region, and spans at most 10,000,000 bases."

addedInput schema / properties / id / minLength
```
Added value: +1
```

addedInput schema / properties / max_length

Added value: +{
+  "default": 10000,
+  "description": "Maximum number of characters in the returned window. Default 10000. Set to 0 to return everything from offset to the end, uncapped.",
+  "maximum": 9007199254740991,
+  "minimum": 0,
+  "type": "integer"
+}

addedInput schema / properties / offset

Added value: +{
+  "default": 0,
+  "description": "0-based character offset where the returned window starts, counted in the resolved sequence (including any expand_5prime/expand_3prime flank). Default 0. Pass nextOffset from a truncated response to fetch the following window; an offset at or past the end returns an empty window.",
+  "maximum": 9007199254740991,
+  "minimum": 0,
+  "type": "integer"
+}

changedInput schema / properties / type / description

Previous value: -"Sequence type to retrieve. genomic: full genomic DNA including introns (default). cdna: spliced transcript sequence (requires ENST… ID). cds: coding sequence only, no UTRs (requires ENST… ID with coding transcript). protein: amino acid sequence (requires ENST… or ENSP… ID)."New value: +"Sequence type to retrieve. genomic: full genomic DNA including introns (default). cdna: spliced transcript sequence (requires ENST… ID). cds: coding sequence only, no UTRs (requires ENST… ID with coding transcript). protein: amino acid sequence (requires ENST… or ENSP… ID). Region ids are genomic-only — request cdna, cds, or protein from a transcript or protein stable ID."

changedOutput schema / anyOf

Previous value: -[
-  {
-    "not": {
-      "required": [
-        "error"
-      ]
-    },
-    "required": [
-      "id",
-      "type",
-      "seq",
-      "length"
-    ]
-  },
-  {
-    "required": [
-      "error"
-    ]
-  }
-]New value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "id",
+      "type",
+      "seq",
+      "length",
+      "offset",
+      "truncated"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `not_found`: The stable ID or region was not found in Ensembl. `type_mismatch`: The requested sequence type is incompatible with the provided ID type. `missing_species`: A bare chr:start-end region was given without a species. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `not_found`: The stable ID or region was not found in Ensembl. `type_mismatch`: A non-genomic type (cdna, cds, or protein) was requested for a region id or a gene ID. `missing_species`: A bare chr:start-end region was given without a species. `invalid_region`: A region id has its start after its end, starts past the end of its sequence region, spans more than the 10,000,000-base maximum, or names a sequence region the species lacks. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "not_found",
-  "type_mismatch",
-  "missing_species"
-]New value: +[
+  "not_found",
+  "type_mismatch",
+  "missing_species",
+  "invalid_region"
+]

changedOutput schema / properties / length / description

Previous value: -"Sequence length in characters — nucleotides for genomic/cdna/cds, amino-acid residues for protein. Use this to budget context window usage before processing the sequence."New value: +"Full sequence length in characters, not the window size — nucleotides for genomic/cdna/cds, amino-acid residues for protein. Includes any expand_5prime/expand_3prime flank."

addedOutput schema / properties / nextOffset

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

addedOutput schema / properties / notice

Added value: +{
+  "description": "Guidance about the window: how to continue when truncated, or why it is empty when the offset is past the end.",
+  "type": "string"
+}

addedOutput schema / properties / offset

Added value: +{
+  "description": "0-based character offset where this window starts.",
+  "type": "number"
+}

changedOutput schema / properties / seq / description

Previous value: -"The full sequence. DNA sequences use IUPAC nucleotide codes (ACGT + ambiguity codes). Protein sequences use single-letter amino acid codes. Large genomic sequences (e.g. 85 kb for BRCA2) are returned in full."New value: +"The requested window of the sequence: at most max_length characters starting at offset. DNA sequences use IUPAC nucleotide codes (ACGT + ambiguity codes); protein sequences use single-letter amino acid codes. Empty when offset is at or past the end."

addedOutput schema / properties / truncated

Added value: +{
+  "description": "True when more sequence follows this window; 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": [
+      "id",
+      "type",
+      "seq",
+      "length"
+    ]
+  },
+  {
+    "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. Declared by this tool: `not_found`: The stable ID or region was not found in Ensembl. `type_mismatch`: The requested sequence type is incompatible with the provided ID type. `missing_species`: A bare chr:start-end region was given without a species. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "not_found",
+            "type_mismatch",
+            "missing_species"
+          ],
+          "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: -[
-  "id",
-  "type",
-  "seq",
-  "length"
-]

Changed2 schema fields changedJul 9, 2026

changedInput schema / properties / id / description

Previous value: -"Ensembl stable ID (ENSG…, ENST…, ENSP…) or region in the format species:chr:start-end (e.g. homo_sapiens:13:32315086-32400268) for region mode. For genomic region queries, species is also required."New value: +"Ensembl stable ID (ENSG…, ENST…, ENSP…) or a genomic region for region mode. Region accepts species:chr:start-end (e.g. homo_sapiens:13:32315086-32400268) or a bare chr:start-end (e.g. 13:32315086-32400268) when the species field is set."

changedInput schema / properties / species / description

Previous value: -"Species in Ensembl internal format (e.g. homo_sapiens). Required for region mode (when id is a species:chr:start-end string). Optional for stable ID lookups — Ensembl infers species from the ID prefix."New value: +"Species in Ensembl internal format (e.g. homo_sapiens). Required for a bare chr:start-end region; optional for the species:chr:start-end form (the embedded species is used when the field is omitted). Optional for stable ID lookups — Ensembl infers species from the ID prefix."

Changed3 schema fields changedJun 22, 2026

addedOutput schema / properties / length

Added value: +{
+  "description": "Sequence length in characters — nucleotides for genomic/cdna/cds, amino-acid residues for protein. Use this to budget context window usage before processing the sequence.",
+  "type": "number"
+}

removedOutput schema / properties / lengthInBp

Removed value: -{
-  "description": "Sequence length in characters (nucleotides or amino acids). Use this to budget context window usage before processing the sequence.",
-  "type": "number"
-}

changedOutput schema / required

Previous value: -[
-  "id",
-  "type",
-  "seq",
-  "lengthInBp"
-]New value: +[
+  "id",
+  "type",
+  "seq",
+  "length"
+]

First observedJun 7, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Annotations only declare read-only/idempotent/open-world, so the description carries the real behavioral burden, and it does: windowing, the truncated flag plus nextOffset walk, max_length 0 semantics, reverse-strand via :-1, and the 10,000,000-base region cap. It stops short of describing error behaviors or response shape in full, but far exceeds the annotation baseline.

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?

Front-loads the core purpose and pagination contract before type selection and region syntax, so an agent can stop reading early. It is dense and long, but nearly every clause carries operational detail rather than filler.

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?

For a complex sequence-fetch tool with 7 parameters, an output schema, and rich annotations, all call-critical details are present: input modes, type semantics, pagination, strand handling, size limits, and prerequisite lookups. Nothing an agent needs to invoke it correctly is missing.

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

Parameters4/5

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

Schema coverage is 100%, so baseline is 3, but the description adds cross-parameter interplay the schema states only in isolation: species-in-id precedence over the species field, expand_5prime/expand_3prime behavior flipping on a :-1 region, and which ID types satisfy each sequence type.

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?

Opens with a specific verb and resource ('Fetch the DNA, cDNA, CDS, or protein sequence') and enumerates the accepted ID/region inputs. It also routes the agent away from a sibling by naming ensembl_lookup_gene for the gene→transcript step, so it is distinguishable without opening other schemas.

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?

States exactly which parameter selection produces which result (genomic/cdna/cds/protein), when region mode applies, and the constraint that protein sequences require a transcript or protein ID — directing the agent to ensembl_lookup_gene first. When-not guidance is implicit but clear (a gene ID cannot serve protein/cdna).

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.

Get Sequence

Input Schema

Output Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources