Register tools

Turn an API's OpenAPI document into tools your agents can use, review them in a manifest, publish them, and manage their lifecycle with hexel.

On this page

Import an OpenAPI document
Choose operations
How operations become tools
Authentication
Review in a manifest
Run it again
Manage the lifecycle
MCP servers

Your agents call your own APIs through tools that you register in a toolkit of your organization. hexel registers many tools at once from an API's OpenAPI document, shows you exactly what it will register before it changes anything, and leaves every new tool as a draft until you publish it.

You need permission to write tools in your organization (tool-gateway:tool:write).

Import an OpenAPI document

See the plan

Point hexel at the document, a file or an https URL, in JSON or YAML. OpenAPI 3 and Swagger 2.0 both work.

Bash

hexel tools import openapi https://api.example.com/openapi.json --toolkit EXAMPLE --dry-run

Toolkit EXAMPLE (Example API) will be created; auth: api_key

ACTION  TOOL            METHOD  PATH              WRITES  NOTE
create  LIST_ORDERS     GET     /v2/orders        no
create  GET_ORDER       GET     /v2/orders/{id}   no
create  CREATE_ORDER    POST    /v2/orders        yes

3 create

Each operation becomes one tool. WRITES marks operations that change data at the destination. A NOTE shows the first problem that would stop the tool from being published.

Register the tools as drafts
Run the same command without --dry-run. hexel shows the plan again and asks before it registers anything; pass --yes to skip the question.
Bash
```
hexel tools import openapi https://api.example.com/openapi.json --toolkit EXAMPLE
```
The toolkit is created in your organization if it doesn't exist. Every tool starts as a draft, which agents can't use.
Publish them
Publishing is your approval: only published tools reach your agents.
Bash
```
hexel tools tool publish --toolkit EXAMPLE --all
```
The registry checks each tool when you publish it, and refuses one it couldn't run, with the reason. Or pass --publish to the import to publish the drafts straight away.

Agents call a tool with a connection of its toolkit: see the console's Connections, or hexel tools connection list.

Choose operations

Flag	Registers
`--read-only`	Only `GET` operations
`--include 'GET /orders*'`	Only operations matching the glob: an operationId, `METHOD /path` or `/path`; repeat for several
`--exclude 'Admin'`	Everything except operations matching the glob
`--tag orders`	Only operations with one of these tags

How operations become tools

OpenAPI	Tool
`operationId`	Slug, in capitals: `listOrders` becomes `LIST_ORDERS`
`summary`, `description`	Name and description; agents read the description to choose a tool
Path, query parameters, JSON or form body	The tool's inputs; path parameters are required
Response `200`, `201` or `202`	The tool's output schema
Method	`GET` tools are marked as not changing data; every other method as changing it
First server, or `--base-url`	The destination, which must be `https`
`info.version`, or `--version`	The tool version

hexel skips an operation it can't register as a tool, and says why. That happens for a request body that isn't JSON or a form (a file upload, for example), a body that isn't an object, a GET or DELETE that requires a body, and a required header or cookie parameter.

Authentication

hexel reads the document's security schemes. The connection's credential is placed the way the scheme describes:

Security scheme	Placement
HTTP bearer, OAuth 2, OpenID Connect	`Authorization: Bearer`
API key in a header or query parameter	That header or query parameter
HTTP basic	`Authorization: Basic`, from the connection's username and password

Operations whose security is empty are registered without authentication. To place the key differently, pass --auth bearer, --auth header:X-Api-Key, --auth query:api_key, --auth basic or --auth none.

Review in a manifest

To review or edit the tools before registering them, write them to a manifest instead:

Bash

hexel tools import openapi spec.yaml --toolkit EXAMPLE --out tools.yaml

The manifest is YAML (or JSON, for a .json file) with the registry's toolkit and tool fields: change descriptions, remove tools or adjust inputs, then register it:

Bash

hexel tools apply -f tools.yaml --dry-run
hexel tools apply -f tools.yaml --publish

Keep the manifest in your repository and run hexel tools apply from CI: with -o json, --dry-run prints the plan as JSON.

Run it again

Importing or applying again is safe. hexel compares each tool with the one already registered:

Action	When
`create`	No tool of that slug and version yet
`update`	A draft that differs: it is updated
`unchanged`	Identical: left alone
`blocked`	A published tool that differs: give the manifest a new version (`--version`)

Manage the lifecycle

Bash

hexel tools tool list --toolkit EXAMPLE --lifecycle all
hexel tools tool publish GET_ORDER --toolkit EXAMPLE
hexel tools tool retire --toolkit EXAMPLE --all       # published tools are deprecated first
hexel tools tool delete --toolkit EXAMPLE --all       # drafts and retired tools
hexel tools toolkit delete EXAMPLE

Name tools by slug, with --toolkit for drafts, or select every tool of a toolkit with --all. retire and delete ask for confirmation.

MCP servers

To register an MCP server's tools instead, register the server, import its tools, and publish them:

Bash

hexel tools mcp register https://mcp.example.com/mcp --slug example --name "Example MCP"
hexel tools mcp import <server-id>
hexel tools tool publish --toolkit <toolkit> --all

mcp import registers each tool as a draft. A server that needs authentication is imported with --connection or --bearer-env.