UTCP Gateway

The Universal Tool Call Protocol (UTCP) gateway provides a plain REST API for listing and invoking tools. UTCP requires no special client library and works with any HTTP client or agent framework.

Gateways page

In the UI

Navigate to Gateways in the sidebar
Click Create Gateway
Select UTCP as the protocol

Create Gateway dialog

Enter a name, slug, and optional description
Click Create
Assign tools from the Tools tab on the gateway detail page

Gateways page — empty state

Configure authentication from the Authentication tab

Your UTCP endpoint is available at:


/utcp/{org-slug}/{gateway-slug}

Via the API

Create a gateway


curl -X POST /gateways \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My UTCP Gateway",
    "type": "utcp",
    "endpoint": "/tools-api"
  }'

List tools


curl /utcp/acme/tools-api/tools \
  -H "Authorization: Bearer $API_KEY"

Response:


{
  "tools": [
    {
      "name": "get_users",
      "description": "Retrieve a list of users with pagination",
      "parameters": {
        "type": "object",
        "properties": {
          "page": { "type": "integer" },
          "limit": { "type": "integer" }
        }
      }
    }
  ]
}

Invoke a tool


curl -X POST /utcp/acme/tools-api/tools/get_users/invoke \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "arguments": {
      "page": 1,
      "limit": 10
    }
  }'

Response:


{
  "result": {
    "users": [
      { "id": "1", "name": "Alice", "email": "alice@example.com" }
    ],
    "total": 42
  },
  "metadata": {
    "duration": 234,
    "toolId": "tool-uuid"
  }
}

Endpoints

Method	Path	Description
`GET`	`/tools`	List all tools on this gateway
`GET`	`/tools/{name}`	Get a single tool definition
`POST`	`/tools/{name}/invoke`	Execute a tool
`GET`	`/health`	Gateway health check

Error codes

Code	HTTP Status	Description
`TOOL_NOT_FOUND`	404	Tool does not exist on this gateway
`INVALID_PARAMS`	400	Parameters failed validation
`EXECUTION_FAILED`	500	Tool execution threw an error
`UNAUTHORIZED`	401	Missing or invalid authentication
`RATE_LIMITED`	429	Too many requests

Integration examples

Python


import requests
 
base = "https://your-instance/utcp/acme/tools-api"
headers = {"Authorization": "Bearer your-api-key"}
 
tools = requests.get(f"{base}/tools", headers=headers).json()["tools"]
 
result = requests.post(
    f"{base}/tools/get_users/invoke",
    headers=headers,
    json={"arguments": {"page": 1, "limit": 10}}
).json()["result"]

JavaScript


const base = "https://your-instance/utcp/acme/tools-api";
const headers = { Authorization: "Bearer your-api-key" };
 
const { tools } = await fetch(`${base}/tools`, { headers }).then(r => r.json());
 
const { result } = await fetch(`${base}/tools/get_users/invoke`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({ arguments: { page: 1, limit: 10 } }),
}).then(r => r.json());