List servers

Lists the external MCP servers the caller's org has registered.

GET /v1/tool/mcp/servers

Tool → · All API references → · Get started →

Address	`https://api.hanzo.ai/v1/tool/mcp/servers`
Method	`GET`
Operation	`get_tool_mcp_servers`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Lists the external MCP servers the caller's org has registered. Each record carries the URL and the name of the header its credential is injected into; the credential VALUE lives only in KMS and is never returned, so hasSecret is the whole of what this surface says about it. Each also says whether its tools could be listed — status, a reason when they could not, and how many there are — so a server that contributes nothing says why.

The whole URL is answered to an admin of the org or a SuperAdmin, who register servers. A member is answered its scheme and host: which server it is, and not a path or query an admin may have put a key in.

Request

GET /v1/tool/mcp/servers takes no parameters and no body — the credential is the whole request.

Response

Status	Body	Meaning
`200`	tool.mcpServerList	ok
`default`	problem-details	refused

200 body — 14 fields.

Field	In	Type	Always	Description
`servers`	body	tool.MCPServer[]	—	Servers is every external MCP server this org has registered.
`servers[].admitted`	body	boolean	—	Admitted is whether an admin of the org, or a SuperAdmin, registered the server.
`servers[].authHeader`	body	string	—	AuthHeader is the request header the KMS-held credential is injected into, e.g. "Authorization".
`servers[].createdAt`	body	integer (int64)	—	CreatedAt is when the server was registered, Unix seconds.
`servers[].hasSecret`	body	boolean	—	HasSecret is whether a credential is sealed in KMS for this server.
`servers[].id`	body	string	—	ID is the server's id within the org.
`servers[].listing`	body	string	—	Listing is the catalog entry this server was enabled from, when it was.
`servers[].name`	body	string	—	Name is the org's label for the server.
`servers[].org`	body	string	—	Org is the org that registered the server — the validated caller's.
`servers[].reason`	body	string	—	Reason says why a server that is not "ok" is not, in words any member may be shown: never the server's address.
`servers[].source`	body	string	—	Source is where the registration came from: "catalog" when it was enabled off the shelf, "org" when the org registered the URL itself.
`servers[].status`	body	string	—	Status is whether the server's tools could be listed when the org's servers were read: "ok", "unreachable", "refused" or "error".
`servers[].tools`	body	integer (int64)	—	Tools is how many tools the server listed, when it listed them.
`servers[].url`	body	string	—	URL is the server's JSON-RPC endpoint.

Failure carries the platform error shape — see Errors.

Examples

CLI

SDK

HTTP

MCP

hanzo tool mcp servers list

.ts

.py

.go

.rs

.java

import { Configuration, ToolApi } from 'hanzoai';

const api = new ToolApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.getToolMcpServers();

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import ToolApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = ToolApi(client).get_tool_mcp_servers()

cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.ToolAPI.GetToolMcpServers(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_client::apis::{configuration::Configuration, tool_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = tool_api::get_tool_mcp_servers(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.ToolApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new ToolApi(client).getToolMcpServers();

curl https://api.hanzo.ai/v1/tool/mcp/servers \
  -H "Authorization: Bearer $HANZO_API_KEY"

MCP reaches tool through the tool tool, which names its 17 operations with its own verbs — this one among them, under a name only MCP declares. describe explains any of them:

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "describe",
         "arguments": {
           "op": "list_tools"
         }
       }
     }'

Tool API · All Hanzo APIs · Interactive reference

Was this page useful?

PreviousList kit NextList authored — GET /v1/tool/plugins/authored