Skip to the content

List an MCP server's tools with their drift

GET /v1/mcp-servers/{mcp_server_id}/tools

Property	Value
Operation	`list_mcp_server_tools`
Group	MCP servers
Scope	`mcp:read`
Route class	`read`
Idempotency	No `Idempotency-Key`
Audit	Not audited: A configuration read; a registration is not Call content and holds no credential.
Released in	1.60.0
Phase 0 host	Served (the hosted api pins 1.65.0)

Lists the tools of the latest listing in name order, and every pinned tool the server no longer lists, each with whether it is allowed, why it cannot be, and its drift from its pin (1.60.0). Descriptions are the server's untrusted text.

Request

Set VOCAL_API to the base URL of your API and VOCAL_API_KEY to an API key with the mcp:read scope (Authentication and keys). Replace each placeholder, such as agt_... or <name>, with your own value.

curl "$VOCAL_API/v1/mcp-servers/mcps_.../tools" \
  -H "Authorization: Bearer $VOCAL_API_KEY"

const response = await fetch(`${process.env.VOCAL_API}/v1/mcp-servers/mcps_.../tools`, {
  headers: {
    Authorization: `Bearer ${process.env.VOCAL_API_KEY}`,
  },
});
console.log(response.status, await response.text());

import os

import requests

response = requests.get(
    f"{os.environ['VOCAL_API']}/v1/mcp-servers/mcps_.../tools",
    headers={
        "Authorization": f"Bearer {os.environ['VOCAL_API_KEY']}",
    },
)
print(response.status_code, response.text)

Parameters

Name	In	Type	Required	Description
`mcp_server_id`	path	McpServerId	yes	The id of an MCP server registration: `mcps_` and the row's UUIDv7 in 26 Crockford base32 characters. Opaque and safe to log.
`limit`	query	integer	no	The page size, 1 to 100.
`cursor`	query	string	no	The opaque `next_cursor` of the previous page; it binds the filters it was issued under.

Responses

Status	Content type	Shape	Error codes
`200`	`application/json`	McpServerToolList
`400`	`application/json`	ErrorEnvelope	`invalid_request`, `invalid_cursor`
`401`	`application/json`	ErrorEnvelope	`unauthenticated`
`403`	`application/json`	ErrorEnvelope	`forbidden`
`404`	`application/json`	ErrorEnvelope	`not_found`
`429`	`application/json`	ErrorEnvelope	`rate_limited`
`500`	`application/json`	ErrorEnvelope	`internal_error`

Fields of the `200` answer

The shape is McpServerToolList.

Field	Type	Required	Description
`data`	array of McpServerTool	yes	The tools of the registration of this page, in name order.
`has_more`	boolean	yes	True when a further page exists.
`next_cursor`	string or null	yes	The cursor of the next page, or null on the last page.
`object`	`"list"`	yes