Custom tools and OpenAPI import

How to define your own HTTP tools, including importing them from an OpenAPI specification. The endpoint contract is in the Tools API reference.

A custom tool hands an agent a handful of endpoints of your own API without writing code. You import an OpenAPI or Postman document, Console turns every operation into an action with a generated input schema, and the agent can call those actions like any other tool.

Open Build → Agents → Tools (/dashboard/agents/tools). New tool opens "Register an upstream API or MCP server as a callable tool."

Import a specification

Section	Fields
Identity	Name (required), Description
Source	Source type: OpenAPI or MCP server
Authentication	None, Bearer token, Custom header (name and value) or Basic auth
API specification (OpenAPI)	Upstream base URL, Specification
MCP endpoint (MCP server)	MCP endpoint URL, Transport (Streamable HTTP or SSE)

The Specification box takes Paste, Upload file (.json, .yaml, .yml) or From URL. The URL is fetched by the server through the SSRF guard, which refuses private-network addresses unless the operator has allowlisted the host. The Format select is Auto-detect, OpenAPI / Swagger (JSON or YAML) or Postman collection; YAML and Postman are normalised into OpenAPI when you save. The field-by-field walkthrough is in Build and publish an agent.

Write specs for a model

The model sees each action's name, description and parameters, nothing else. Give every operation a clear summary or description that says when to use it, and an operationId that reads like a verb phrase. Leave out the operations an agent should never call.

Authentication secrets are encrypted at rest and masked in responses.

The tool page

Part	What it does
Actions (N)	Every action discovered from the source; each becomes one callable function
Playground	Runs one action against the real upstream
Request Logs	Every action call, from agent runs and from the Playground
Sync Actions	Re-reads the source after your upstream changed
Accept caller headers	Off by default. When on, API callers can forward their own headers (for example their own Authorization) to the upstream per request

Status Active or Disabled applies to the whole tool: a disabled tool is skipped at run time even if an agent still has it bound.

Choose which actions an agent gets

An agent binds a tool by choosing individual actions in the Select Tools dialog, so one imported API can serve several agents with different permissions. Bind only what the agent needs; see Tools overview.

When you need more control: an MCP server with an OpenAPI source

A custom tool is the shortest path for agents. When you also need to switch single tools off, rename or reword them, set your own key, or let external MCP clients use the same API, create an MCP server with the OpenAPI spec source instead. It uses the same importer, and adds:

Control	Where	Notes
Per-tool enable and disable	Server → Tools tab	Stored as disabledTools; hidden from tools/list, the client API and every bound agent
Tool name override	Edit description & annotations → Tool name	Letters, numbers, _, -; at most 128 characters; unique on the server
Description override	Same dialog	Replaces the text discovered from the spec
Custom key	Server Key on the Overview tab, or key on create	The identifier agents bind by and the API path segment; rename asks for confirmation
Custom public path	Custom path in Endpoint exposure, public servers only	At least 8 characters, unique in the workspace

Custom tools themselves have an auto-generated key and no per-action switch; to hide one action, remove it from the spec and use Sync Actions, or do not select it in the agent.

Use a tool directly

With an API token you can list tools, read one and run an action:

curl -X POST "$BASE/api/client/v1/tools/weather-api/actions/get-current-weather/execute" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "arguments": { "location": "Istanbul" } }'

The client API can also create (POST /api/client/v1/tools), update (PATCH /api/client/v1/tools/{toolKey}), delete and sync (POST /api/client/v1/tools/{toolKey}/sync) tools. See the Tools API.

Who can do this

Custom tools belong to the tools service (Agent Tools). Reading needs tools.read, creating and changing needs tools.write, and running an action through the API is checked as tool.execute. See the Permissions reference.