Skip to main content

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:

FieldsResolves to
mcpId and toolNameThat server's tool of that name
toolName as the namespaced name, mcp_<server>_<tool>The first server matching the middle part
mcpName and toolNameThe 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.

FieldMeaning
resultThe tool's own result: content[] and isError
errorEmpty 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, policiesAppliedA 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, approvalStatusThe policy wants a human decision; approvalStatus is pending, later consumed or denied
toolName, mcpName, mcpId, latencyMsWhat ran and how long it took

Quick start​

Run a read tool and branch on the outcome:

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"}}'

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.

The Control Room's Approvals page listing pending tool-call requests with their tool, requester and age, and approve and deny controls.The Control Room's Approvals page listing pending tool-call requests with their tool, requester and age, and approve and deny controls.
Approvals in the Control Room: tool calls parked by a policy wait here for a reviewer with the approve capability to approve or deny them.

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 presentWhat happens
An id still pendingThe same id, and a message that it is still waiting for a reviewer
An id already used, expired or unknownA new pending request is raised; the message says why the old one did not apply
An id granted for a different tool, server or argumentsA new pending request for this call
A denied idblocked 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.

The Control Room's Policies page with a table of rules showing status, action, scope and priority.The Control Room's Policies page with a table of rules showing status, action, scope and priority.
Policies in the Control Room: each rule with its status, action, scope and priority, with Create Policy to add one.

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_TIMEOUT while 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.isError true, result.error_type result_too_large and the same text in error. 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 error set to Rate limit exceeded, retry_after_seconds and a Retry-After header, 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 policyName set to injection_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_BLOCKED and APPROVAL_REQUIRED codes in the error catalogue are not used by this route; the outcomes above are its only shapes.

Troubleshooting​

  • error says Tool not found: the name form did not resolve. Pass mcpName or mcpId with the plain toolName, or use namespacedName from the list.
  • blocked with policyName capability:deny_list: the key's user is on the tenant's emergency deny-list; an administrator lifts it.
  • blocked with a rail in policyName: an argument matched an injection pattern; the message names the rails.
  • blocked saying the request could not be safety-checked: the guardrail check was unreachable; retry shortly.
  • requiresApproval with an empty approvalId: the request could not be recorded; retry, and the id comes back.
  • 403 FORBIDDEN whose detail names an internal service token: the platform's own token between its gateways is missing; an administrator, not your key.
  • 401 Invalid or expired API key although the key works elsewhere: the key lacks the Execute tools scope, which the gateway checks while validating the key.

The same call elsewhere

Describes the platform as of .

Was this page helpful?