# List servers

URL: https://docs.hanzo.ai/docs/openapi/tool/get-tool-mcp-servers

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

`GET /v1/tool/mcp/servers`

> [Tool →](https://docs.hanzo.ai/docs/openapi/tool) · [All API references →](https://docs.hanzo.ai/docs/openapi) · [Get started →](https://docs.hanzo.ai/docs/guides)

|               |                                            |
| ------------- | ------------------------------------------ |
| **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](https://docs.hanzo.ai/docs/errors).

## Examples

**CLI**

```bash
hanzo tool mcp servers list
```

**SDK**

**.ts**

```ts
import { Configuration, ToolApi } from 'hanzoai';

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

**.py**

```python
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()
```

**.go**

```go
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
}
```

**.rs**

```rust
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?;
```

**.java**

```java
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();
```

**HTTP**

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

**MCP**

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:

```bash
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](https://docs.hanzo.ai/docs/openapi/tool) · [All Hanzo APIs](https://docs.hanzo.ai/docs/openapi) · [Interactive reference](https://docs.hanzo.ai/docs/openapi/reference)