Create servers

POST /v1/tool/mcp/servers

Gives the caller's org one more external MCP server, so its tools join the org's tool plane and the fleet's MCP server. It is the ONE way an org gains a server, whether it typed the URL in or enabled a catalog listing: both write the SAME record, and source says which it was. A second registration path would be a second place for a server to exist, and then a second place to forget to check the credential.

The credential VALUE is sealed in KMS under a per-org ref; the row keeps only the URL, the header name to inject it into, and a has-secret flag — so a secret with no KMS configured is refused 503 rather than stored in the clear. The URL is SSRF-validated here and re-checked by the dialer at connect time, which is the DNS-rebinding defense.

Enabling a listing the org already enabled REVISES that server rather than adding a near-duplicate beside it, so a retried enable is the same one server. Answers 201 with the stored record.

A server and the tools of it the org activates are carried into every agent run in the org, so registering one — or revising one, credential included — takes an admin of the org or a SuperAdmin; a member is refused 403. The registration is on the org's audit trail before it is made, and one the trail cannot record is refused 503.

Request

5 fields, body application/json (required).

Response

201 body — 13 fields.

Failure carries the platform error shape — see Errors.

Examples

hanzo tool mcp servers create

import { Configuration, ToolApi } from 'hanzoai';

const api = new ToolApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postToolMcpServers({ authHeader: "<authHeader>", listing: "<listing>" });

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).post_tool_mcp_servers(auth_header="<authHeader>", listing="<listing>")

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

resp, _, err := client.ToolAPI.PostToolMcpServers(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::post_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).postToolMcpServers();

curl -X POST https://api.hanzo.ai/v1/tool/mcp/servers \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "authHeader": "<authHeader>",
       "listing": "<listing>"
     }'

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