Custom tools
Turn your own REST API or a remote MCP server into tools your agents can call.
Two ways to add tools the catalog does not have. Both run per user with that user's credential, and are logged and audited like catalog tools. Agent sessions find and run them like catalog tools, within the session's options.
| Source | Dashboard page | Connector id | Tool id |
|---|---|---|---|
| REST API | Build → REST APIs | openapi:<prefix> | openapi_<prefix>_<operation> |
| MCP server | Build → MCP servers | mcp:<id> | mcp_<id>_<tool> |
REST APIs
Add the spec
In the dashboard, open Build → REST APIs and click Import spec. Paste an OpenAPI 3.0 or 3.1 spec, upload it as a file, or enter its public https URL (JSON or YAML, up to 2 MB and 500 operations), then click Read spec. A linked spec is downloaded once, when you read it. Nothing is stored yet.
Name it
Set Name and Tool prefix (lowercase letters, numbers and dashes, up to 40, unique in the project). Check Base URL: it comes from the spec's first absolute server and must be a public https URL.
Choose authentication
Under How users sign in, Dexby starts from the spec's securitySchemes: a Bearer token, a key in
a header or query parameter, HTTP Basic, and OAuth 2.0 sign-in or client credentials. Edit them or
add more:
- API key or token: sent as
Authorization: Bearer, in a header (with an optional prefix such asToken), in a query parameter, or as the HTTP Basic username. - Username and password: sent as HTTP Basic.
- OAuth 2.0 sign-in: the authorization and token URLs, scopes, and how the client goes to the token URL.
- OAuth 2.0 client credentials: the token URL and scopes. Users enter a client ID and secret.
- Custom fields: the fields users enter, and the headers or query parameters that send them,
written as
{field}.
Edit as JSON takes any method a built-in connector can use, in the connector spec's
authMethods format, such as a login exchange or request signing. No method means no sign-in. The
methods are checked like a connector's, and each call places the credential, renews tokens and signs
in again exactly as built-in connectors do.
Dexby creates an auth config with key openapi:<prefix> for the first method
that needs no OAuth client, and each user connects their own credential. For an OAuth sign-in, add
an auth config with your client ID and secret first.
Pick operations and import
GET operations start selected. Select individual write operations you want to expose. Choose the
data each one handles (General, Personal data or Health data), then click Import N operations.
How an operation becomes a tool:
| Part | Rule |
|---|---|
| Tool id | openapi_<prefix>_ plus the operationId in snake case (listOrders → list_orders), else method and path (get /orders/{id} → get_orders_id). Max 64 characters; duplicates get _2. |
| Effect | read for GET, write for POST, PUT, PATCH and DELETE. Other methods are skipped. |
| Input | One property per path, query and header parameter, plus the JSON body under body. |
| Description | The summary, else the description, else method and path. |
Calls time out after 30 seconds and refuse redirects. A provider error returns 502 UPSTREAM_ERROR
with the status only; a revoked credential returns REAUTH_REQUIRED.
Edit changes an imported API in place: its name, logo, base URL and sign-in methods, which
operations stay, and the data each one handles. An unticked operation is deleted with its
tool; at least one must stay. The tool prefix and tool ids do not change. A sign-in method that an
auth config still uses cannot be removed (409 AUTH_CONFIG_IN_USE); delete that auth config first.
To add operations, import the spec again under a new prefix. Remove deletes the API and erases
every connected credential.
MCP servers
Only remote servers are supported (Streamable HTTP or HTTP+SSE), not local stdio servers.
Add the server
Open Build → MCP servers and click Add MCP server. Fill in Name, Id and MCP
endpoint (the server's public https URL, such as https://mcp.example.com/mcp). The Id is
lowercase letters, numbers and dashes, unique in the project. It becomes connector id mcp:<id> and
tool ids mcp_<id>_<tool>.
Choose authentication
Under Accepted authentication, tick API key or token (sent as Authorization: Bearer, or in
Header name if you set one), OAuth 2.0 (enter Authorize URL and Token URL, and register
the Redirect URL shown with the provider), both, or neither.
Save and connect
Click Add server. Dexby connects and discovers the tools. With an API key method, Dexby also
creates an auth config for mcp:<id>, so you can
connect accounts straight away from Connections, a user's page or a
connect link, as for any app. For OAuth, open Sign-in & accounts on the server's page and add
your client ID and secret first.
Discovery uses default's connected accounts. If listing tools needs a credential, connect an
account for default, then click Refresh. Tool calls use only the calling user's own
connection, chosen and checked as for any app: a user without one gets MISSING_CONNECTION, and
an auth config that turned a tool off refuses it. Only a server with no sign-in method runs
without a credential.
MCP server tools have no declared classification, so they are treated as pii and write.
Refresh and review changes
Refresh rediscovers the tool list. A server shows Active, Unreachable or Auth failed.
When a discovery finds changed tool names, descriptions or schemas, the server shows Tool
definitions changed on a date and the tools keep running. A change found by Refresh also sends
the mcp_server.tools_changed webhook. Review the tools, then click Mark reviewed to clear the
flag.
Edit changes the name, URL, description, category, logo and sign-in. A new URL rediscovers the
tools. A sign-in change that drops a method an auth config uses is refused with
AUTH_CONFIG_IN_USE; remove that auth config first.
Remove erases every connected credential, then deletes the server, its connections and its auth configs.