Execute a governed tool
POST /public/v1/tools/execute runs a tool from the tenant's catalogue: an MCP server's tool, a hosted or OpenAPI-backed one, or a database tool. On the way the call passes the platform's governance: the emergency deny-list, the guardrail tool rails, the tool policy for that tool and, when the policy says so, a human decision in the Control Room. Every outcome, a refusal included, is a 200 with the same body. Read the fields, not the status.
Who can use it: anyone holding an API key with the Execute tools scope, which also lists the catalogue. Policies are set by administrators on the Control Room's Policies page; approvals are decided by reviewers with the approve capability.
Find the tool
GET /public/v1/tools returns tools[], each with name, namespacedName (mcp_<server>_<tool>), description, inputSchema, mcpName, mcpId, kind (READ or WRITE) with kindBasis, sourceKind and riskLevel, plus total, mcpCount, truncated and undiscoveredSources for servers whose tools could not be read. Filter with mcp_name, kind, source_kind, basis, q, limit (up to 1000; left out, everything) and offset.
kind says whether a tool may change something. When the server declares it, kindBasis is annotation; otherwise it comes from the HTTP verb of an OpenAPI tool or from the name, erring on the side of WRITE. Treat WRITE as "may mutate", not as certain.
Name the tool in the call one of three ways:
| Fields | Resolves to |
|---|---|
mcpId and toolName | That server's tool of that name |
toolName as the namespaced name, mcp_<server>_<tool> | The first server matching the middle part |
mcpName and toolName | The tool on the server of that name |
A bare toolName with neither hint does not resolve and comes back as error set to Tool not found.
The request and the response
The body takes toolName, arguments, mcpId, mcpName, sessionId (groups calls into one MCP session for servers that keep state) and approvalId. tenantId and userId are overwritten from the key.
| Field | Meaning |
|---|---|
result | The tool's own result: content[] and isError |
error | Empty on success. A sentence when the tool failed, was not found, ran out of time, or returned more than the result cap allows |
blocked, message, policyName, policiesApplied | A refusal: by the tool policy (Blocked by tool policy: <id>), by the deny-list (capability:deny_list) or by a rail (tool_sql_injection, tool_path_traversal, tool_command_injection) |
requiresApproval, approvalId, approvalStatus | The policy wants a human decision; approvalStatus is pending, later consumed or denied |
toolName, mcpName, mcpId, latencyMs | What ran and how long it took |
Quick start
Run a read tool and branch on the outcome:
- cURL
- Python
- TypeScript
curl -X POST "https://<your tenant host>/public/v1/tools/execute" \
-H "Authorization: Bearer kapi_..." \
-H "Content-Type: application/json" \
-d '{"mcpName": "crm", "toolName": "lookup_account", "arguments": {"account_id": "A-4471"}}'
import requests
BASE = "https://<your tenant host>/public/v1"
HEADERS = {"Authorization": "Bearer kapi_..."}
def run_tool(call):
r = requests.post(f"{BASE}/tools/execute", headers=HEADERS, json=call)
r.raise_for_status() # only transport and key errors are non-200
out = r.json()
if out.get("blocked"):
raise PermissionError(f"{out['policyName']}: {out['message']}")
if out.get("requiresApproval"):
return {"pending": out["approvalId"], "message": out["message"]}
if out.get("error"):
raise RuntimeError(out["error"])
return out["result"]
call = {"mcpName": "crm", "toolName": "lookup_account", "arguments": {"account_id": "A-4471"}}
outcome = run_tool(call)
if "pending" in outcome:
print("held for approval:", outcome["pending"]) # resend `call` with approvalId once decided
else:
print(outcome["content"])
const BASE = "https://<your tenant host>/public/v1";
const headers = { Authorization: "Bearer kapi_...", "Content-Type": "application/json" };
async function runTool(call: Record<string, unknown>) {
const r = await fetch(`${BASE}/tools/execute`, { method: "POST", headers, body: JSON.stringify(call) });
if (!r.ok) throw new Error(`${r.status} ${await r.text()}`); // only transport and key errors are non-200
const out = await r.json();
if (out.blocked) throw new Error(`${out.policyName}: ${out.message}`);
if (out.requiresApproval) return { pending: out.approvalId as string, message: out.message as string };
if (out.error) throw new Error(out.error);
return out.result;
}
const call = { mcpName: "crm", toolName: "lookup_account", arguments: { account_id: "A-4471" } };
const outcome = await runTool(call);
if ("pending" in outcome) console.log("held for approval:", outcome.pending); // resend `call` with approvalId once decided
else console.log(outcome.content);
When approval is required
A policy of manual on the tool holds the call. The response carries requiresApproval true and an approvalId; the request appears on the Control Room's Approvals page, where a reviewer with the approve capability approves or denies it. Nothing notifies the reviewer on the current build, and the queue does not refresh itself. A reviewer cannot decide their own request.


To resume, resend the same call, the same tool on the same server with the same arguments, with approvalId in the body. The approval is spent by that one call and the response comes back executed with approvalStatus set to consumed. A request that is not decided within 24 hours expires. Calling again with the same arguments while the request is pending returns the same approvalId rather than raising a second one.
| You present | What happens |
|---|---|
| An id still pending | The same id, and a message that it is still waiting for a reviewer |
| An id already used, expired or unknown | A new pending request is raised; the message says why the old one did not apply |
| An id granted for a different tool, server or arguments | A new pending request for this call |
| A denied id | blocked true, approvalStatus denied, and a message naming who declined and their note |
An approval never bypasses the deny-list, the rails or a block policy. Policies are manual (hold for approval), block, auto_approve, or monitor (allow and record); a tool with no policy is allowed, and where several match, manual wins over block, which wins over monitor.


Limits and behaviour
- The tool gateway allows a tool 240 seconds, but the public API gateway waits 60 seconds for the response, so a slower tool answers 504
UPSTREAM_TIMEOUTwhile it keeps running and its result is lost. Keep long tools inside an agent. - A result over 4 MiB is discarded and replaced by
result.isErrortrue,result.error_typeresult_too_largeand the same text inerror. Request bodies are capped at 10 MiB. - The tool gateway has its own limit of 600 calls per minute per tenant, answered as 429 with
errorset toRate limit exceeded,retry_after_secondsand aRetry-Afterheader, in addition to the key's limit. - The rails are off until a guardrail profile enables them. When the rail check cannot run, the call is blocked, not allowed, with
policyNameset toinjection_tool_check; a failure to read policies blocks the same way. - Every call, allowed or not, writes a governance audit event carrying the approval id.
- The
POLICY_BLOCKEDandAPPROVAL_REQUIREDcodes in the error catalogue are not used by this route; the outcomes above are its only shapes.
Troubleshooting
errorsaysTool not found: the name form did not resolve. PassmcpNameormcpIdwith the plaintoolName, or usenamespacedNamefrom the list.blockedwithpolicyNamecapability:deny_list: the key's user is on the tenant's emergency deny-list; an administrator lifts it.blockedwith a rail inpolicyName: an argument matched an injection pattern; the message names the rails.blockedsaying the request could not be safety-checked: the guardrail check was unreachable; retry shortly.requiresApprovalwith an emptyapprovalId: the request could not be recorded; retry, and the id comes back.- 403
FORBIDDENwhosedetailnames an internal service token: the platform's own token between its gateways is missing; an administrator, not your key. - 401
Invalid or expired API keyalthough the key works elsewhere: the key lacks the Execute tools scope, which the gateway checks while validating the key.
The same call elsewhere