uniprot-mcp-server

uniprot-mcp-server: get taxonomy

uniprot_get_taxonomy

Read-onlyIdempotent

Resolve a taxonomy record by NCBI taxon ID (e.g. 9606) or organism name (e.g. "Homo sapiens" or "human") — provide exactly one. Exact case-insensitive scientific names take priority, then common names, mnemonic and aliases; stray double quotes and backslashes are tolerated after exact matching. Ties and partial matches return candidate taxon IDs instead of guessing. Returns the scientific and common name, mnemonic, rank, parent, and full lineage. Set include_children for immediate child taxa in pages of 100; pass the returned cursor for the next page. Use the resolved taxon ID with uniprot_search_proteins (organism_id) or uniprot_get_proteome (taxon_id).

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "uniprot_get_taxonomy"
  }
}

Input Schema

Name	Required	Description
`name`	No	Organism name, e.g. "Homo sapiens" or "human". Exact case-insensitive scientific names take priority, then common names, mnemonic and aliases. Stray double quotes and backslashes are tolerated only after exact matching; ties require taxon_id. Provide this OR taxon_id, not both.
`cursor`	No	Forward-pagination cursor from a prior children page, for the next page of the same taxon; a cursor issued for another taxon is rejected. Only meaningful with include_children.
`taxon_id`	No	NCBI taxonomy ID, e.g. 9606. Provide this OR name, not both.
`include_children`	No	When true, also fetch a page of up to 100 immediate child taxa via a follow-up search. Defaults to false.

Output Schema

Name	Required	Description
`cap`	No	The page size that was applied, when more remain.
`error`	No	Present when the call failed. Absent on success.
`shown`	No	Number of children on this page, when more remain.
`taxon`	No	The taxonomy record.
`cursor`	No	Forward cursor for the next children page. Absent on the last page.
`notice`	No	Paging guidance when more children remain — the total and how to continue.
`lineage`	No	Full lineage from root to the taxon's near ancestor.
`children`	No	One page of immediate children (up to 100). Present only when include_children is true.
`truncated`	No	True when more children remain past this page — fetch them with cursor.
`childCount`	No	Number of immediate children on this page (when include_children is true).
`totalChildren`	No	Total immediate children of the taxon across all pages (when include_children is true).

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedNov 4, 2026

changedInput schema / properties / name / description

Previous value: -"Organism scientific name, e.g. \"Homo sapiens\". Provide this OR taxon_id, not both. Matched against the scientific name."New value: +"Organism name, e.g. \"Homo sapiens\" or \"human\". Exact case-insensitive scientific names take priority, then common names, mnemonic and aliases. Stray double quotes and backslashes are tolerated only after exact matching; ties require taxon_id. Provide this OR taxon_id, not both."

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

Previous value: -"Machine-readable failure mode. Declared by this tool: `missing_identifier`: Neither taxon_id nor name was provided. `conflicting_identifier`: Both taxon_id and name were provided. `not_found`: The taxon ID or name did not resolve to a record. `invalid_cursor`: The cursor was issued for another taxon, is malformed, or UniProt could not continue from it. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `incomplete_candidates`: The 45-second name lookup budget expires before all candidate pages are checked. `ambiguous_name`: Multiple taxa share the best exact name match. `no_exact_match`: Only partial candidate names match. `missing_identifier`: Neither taxon_id nor name was provided. `conflicting_identifier`: Both taxon_id and name were provided. `not_found`: The taxon ID or name did not resolve to a record. `invalid_cursor`: The cursor was issued for another taxon, is malformed, or UniProt could not continue from it. Other values are possible when a failure originates below the handler."

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

Previous value: -[
-  "missing_identifier",
-  "conflicting_identifier",
-  "not_found",
-  "invalid_cursor"
-]New value: +[
+  "incomplete_candidates",
+  "ambiguous_name",
+  "no_exact_match",
+  "missing_identifier",
+  "conflicting_identifier",
+  "not_found",
+  "invalid_cursor"
+]

Changed12 schema fields changedOct 14, 2026

addedInput schema / properties / cursor

Added value: +{
+  "description": "Forward-pagination cursor from a prior children page, for the next page of the same taxon; a cursor issued for another taxon is rejected. Only meaningful with include_children.",
+  "type": "string"
+}

changedInput schema / properties / include_children / description

Previous value: -"When true, also fetch the immediate child taxa via a follow-up search. Defaults to false."New value: +"When true, also fetch a page of up to 100 immediate child taxa via a follow-up search. Defaults to false."

addedOutput schema / properties / cap

Added value: +{
+  "description": "The page size that was applied, when more remain.",
+  "type": "number"
+}

changedOutput schema / properties / childCount / description

Previous value: -"Number of immediate children returned (when include_children is true)."New value: +"Number of immediate children on this page (when include_children is true)."

changedOutput schema / properties / children / description

Previous value: -"Immediate children. Present only when include_children is true."New value: +"One page of immediate children (up to 100). Present only when include_children is true."

addedOutput schema / properties / cursor

Added value: +{
+  "description": "Forward cursor for the next children page. Absent on the last page.",
+  "type": "string"
+}

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

Previous value: -"Machine-readable failure mode. Declared by this tool: `missing_identifier`: Neither taxon_id nor name was provided. `conflicting_identifier`: Both taxon_id and name were provided. `not_found`: The taxon ID or name did not resolve to a record. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `missing_identifier`: Neither taxon_id nor name was provided. `conflicting_identifier`: Both taxon_id and name were provided. `not_found`: The taxon ID or name did not resolve to a record. `invalid_cursor`: The cursor was issued for another taxon, is malformed, or UniProt could not continue from it. Other values are possible when a failure originates below the handler."

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

Previous value: -[
-  "missing_identifier",
-  "conflicting_identifier",
-  "not_found"
-]New value: +[
+  "missing_identifier",
+  "conflicting_identifier",
+  "not_found",
+  "invalid_cursor"
+]

addedOutput schema / properties / notice

Added value: +{
+  "description": "Paging guidance when more children remain — the total and how to continue.",
+  "type": "string"
+}

addedOutput schema / properties / shown

Added value: +{
+  "description": "Number of children on this page, when more remain.",
+  "type": "number"
+}

addedOutput schema / properties / totalChildren

Added value: +{
+  "description": "Total immediate children of the taxon across all pages (when include_children is true).",
+  "type": "number"
+}

addedOutput schema / properties / truncated

Added value: +{
+  "description": "True when more children remain past this page — fetch them with cursor.",
+  "type": "boolean"
+}

First observedAug 22, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations only declare readOnly/idempotent/openWorld; the description adds real behavioral detail beyond them — matching precedence, tolerance of stray quotes and backslashes only after exact matching, refusal to guess on ties, pagination in pages of 100, and cursor scoping. These are the non-obvious traits that determine whether a call succeeds or surprises the agent.

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-loaded with the core resolve action and identifier rule, then behavior, then return shape, then downstream usage — a sensible order. It is dense, packing several clauses into em-dash-linked sentences, but nothing is filler and every clause carries a distinct constraint.

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 four-parameter, zero-required read tool with a full output schema and rich annotations, the description covers everything an agent needs: identifier exclusivity, matching semantics, tie handling, pagination, and where the resolved ID is consumed. Return fields are listed even though the output schema could carry them.

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; the description still adds operational meaning by explaining that the cursor must be the one returned for this taxon and that include_children triggers a paged follow-up search. It largely mirrors the schema's wording on the 100-item page size, so it is additive rather than fully compensating.

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 (resolve) and resource (taxonomy record) and states the two accepted identifiers with concrete examples. It is unmistakably distinct from siblings like uniprot_get_entry or uniprot_get_proteome, and it names those siblings as downstream consumers.

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?

Explicitly states the 'provide exactly one' constraint, the precedence order for name matching (scientific, then common, mnemonic, aliases), and the fallback behavior when ties or partial matches occur. It also routes the agent onward to uniprot_search_proteins (organism_id) and uniprot_get_proteome (taxon_id), which is precisely the when-to-use-which guidance an agent needs.

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

All uniprot-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.