uniprot-mcp-server

uniprot-mcp-server: get proteome

uniprot_get_proteome

Read-onlyIdempotent

Fetch the reference proteome for an organism by UPID (e.g. "UP000005640") or NCBI taxon ID (e.g. 9606) — provide exactly one. Returns metadata inline: proteome type, total protein count, BUSCO completeness (score, complete/fragmented/missing counts, lineage dataset), and the genome assembly accession. The protein set is opt-in via include_proteins (it is large — human is ~147,506) and returns a capped page with a forward cursor; narrow it with the query filter (UniProtKB Lucene syntax) for a subset. Resolve an organism name to a taxon ID first with uniprot_get_taxonomy.

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_proteome"
  }
}

Input Schema

Name	Required	Description
`size`	No	Proteins per page when include_proteins is true (max 500). Omit for the server default.
`upid`	No	Proteome UPID. Provide this OR taxon_id, not both.
`query`	No	Optional UniProtKB Lucene filter to narrow the protein list, e.g. "reviewed:true AND keyword:KW-0067". Only applies when include_proteins is true.
`cursor`	No	Opaque cursor from this tool for the same resolved UPID and exact query. Identifier aliases resolving to that UPID and size changes are allowed. Older raw cursors are rejected; restart without cursor. Only meaningful with include_proteins.
`taxon_id`	No	NCBI taxon ID, e.g. 9606 for human. Prefers an exact reference proteome; otherwise resolves a unique descendant reference, or returns candidate UPIDs and taxon IDs for explicit selection. Provide this OR upid, not both.
`include_proteins`	No	When true, also return a capped, cursor-paginated page of the proteome's proteins. Defaults to false — metadata alone is the common case.

Output Schema

Name	Required	Description
`cap`	No	The page-size cap that was applied.
`error`	No	Present when the call failed. Absent on success.
`query`	No	The protein filter as supplied by the caller.
`shown`	No	Number of proteins returned in this page.
`cursor`	No	Forward cursor for the next protein page. Absent on the last page.
`notice`	No	Truncation guidance when the protein page was capped — how to reach the rest (walk the cursor or narrow with the query filter).
`proteins`	No	A capped page of the proteome's proteins. Present only when include_proteins is true.
`proteome`	No	Proteome metadata.
`truncated`	No	True when the protein page hit the size cap — more remain via cursor.
`totalProteinsMatched`	No	Total proteins matching the (optionally filtered) proteome query.

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedNov 4, 2026

changedInput schema / properties / taxon_id / description

Previous value: -"NCBI taxon ID, e.g. 9606 for human. Resolves to the reference proteome. Provide this OR upid, not both."New value: +"NCBI taxon ID, e.g. 9606 for human. Prefers an exact reference proteome; otherwise resolves a unique descendant reference, or returns candidate UPIDs and taxon IDs for explicit selection. Provide this OR upid, not both."

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

Previous value: -"Machine-readable failure mode. Declared by this tool: `missing_identifier`: Neither upid nor taxon_id was provided. `conflicting_identifier`: Both upid and taxon_id were provided. `not_found`: The UPID or taxon has no reference proteome. `invalid_query`: The query filter has unbalanced parentheses (rejected before any request), or UniProtKB rejected it — the message names the rejected field or syntax. `invalid_cursor`: The protein cursor is malformed, from an older version, belongs to another tool, resolved UPID or query, or UniProt could not continue from it (HTTP 500). Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `ambiguous_proteome`: Multiple descendant reference proteomes exist or candidate pages remain. `missing_identifier`: Neither upid nor taxon_id was provided. `conflicting_identifier`: Both upid and taxon_id were provided. `not_found`: The UPID or taxon has no reference proteome. `invalid_query`: The query filter has unbalanced parentheses (rejected before any request), or UniProtKB rejected it — the message names the rejected field or syntax. `invalid_cursor`: The protein cursor is malformed, from an older version, belongs to another tool, resolved UPID or query, or UniProt could not continue from it (HTTP 500). 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_query",
-  "invalid_cursor"
-]New value: +[
+  "ambiguous_proteome",
+  "missing_identifier",
+  "conflicting_identifier",
+  "not_found",
+  "invalid_query",
+  "invalid_cursor"
+]

addedOutput schema / properties / query

Added value: +{
+  "description": "The protein filter as supplied by the caller.",
+  "type": "string"
+}

Changed2 schema fields changedOct 22, 2026

changedInput schema / properties / cursor / description

Previous value: -"Forward-pagination cursor from a prior protein page. Only meaningful with include_proteins."New value: +"Opaque cursor from this tool for the same resolved UPID and exact query. Identifier aliases resolving to that UPID and size changes are allowed. Older raw cursors are rejected; restart without cursor. Only meaningful with include_proteins."

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

Previous value: -"Machine-readable failure mode. Declared by this tool: `missing_identifier`: Neither upid nor taxon_id was provided. `conflicting_identifier`: Both upid and taxon_id were provided. `not_found`: The UPID or taxon has no reference proteome. `invalid_query`: The query filter has unbalanced parentheses (rejected before any request), or UniProtKB rejected it — the message names the rejected field or syntax. `invalid_cursor`: UniProt could not continue from the protein cursor (it answered HTTP 500) — the cursor is malformed or truncated. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `missing_identifier`: Neither upid nor taxon_id was provided. `conflicting_identifier`: Both upid and taxon_id were provided. `not_found`: The UPID or taxon has no reference proteome. `invalid_query`: The query filter has unbalanced parentheses (rejected before any request), or UniProtKB rejected it — the message names the rejected field or syntax. `invalid_cursor`: The protein cursor is malformed, from an older version, belongs to another tool, resolved UPID or query, or UniProt could not continue from it (HTTP 500). Other values are possible when a failure originates below the handler."

Changed2 schema fields changedOct 14, 2026

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

Previous value: -"Machine-readable failure mode. Declared by this tool: `missing_identifier`: Neither upid nor taxon_id was provided. `conflicting_identifier`: Both upid and taxon_id were provided. `not_found`: The UPID or taxon has no reference proteome. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `missing_identifier`: Neither upid nor taxon_id was provided. `conflicting_identifier`: Both upid and taxon_id were provided. `not_found`: The UPID or taxon has no reference proteome. `invalid_query`: The query filter has unbalanced parentheses (rejected before any request), or UniProtKB rejected it — the message names the rejected field or syntax. `invalid_cursor`: UniProt could not continue from the protein cursor (it answered HTTP 500) — the cursor is malformed or truncated. 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_query",
+  "invalid_cursor"
+]

First observedAug 22, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses the response contents (proteome type, protein count, BUSCO completeness, assembly accession), the size of the protein payload (~147,506 for human), pagination via forward cursor, and cursor invalidation rules (raw cursors rejected, restart without cursor, size changes tolerated). This is behavior an agent cannot infer from structured fields.

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 purpose and identifier choice, then escalating to return shape, then opt-in protein payload and cursor caveats. Dense and mostly waste-free, though the cursor caveats are packed into a single long clause that takes a second read.

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 6-parameter, output-schema-backed read tool, the description covers identifier resolution, opt-in payload behavior, filtering, and pagination. Nothing an agent needs to call it correctly or to avoid the oversized protein fetch 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; the description still adds operational meaning by reinforcing the exactly-one rule for upid/taxon_id and by quantifying why size and query matter ("it is large — human is ~147,506"). The Lucene syntax note largely duplicates the schema, limiting it to a modest gain over baseline.

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?

States a specific verb plus resource ("Fetch the reference proteome for an organism") and gives both accepted identifiers with concrete examples. An agent can immediately distinguish this from uniprot_get_entry, uniprot_get_sequence, and uniprot_search_proteins.

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

Usage Guidelines4/5

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

Explicit constraints and prerequisites: "provide exactly one" identifier, "Resolve an organism name to a taxon ID first with uniprot_get_taxonomy", and the note that include_proteins is opt-in and large. It does not contrast itself against uniprot_search_proteins for the case of finding proteomes without a known organism, so it falls short of full when-not guidance.

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.

uniprot-mcp-server: get proteome

Tool call template

Input Schema

Output Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources