Custom Tools
apistash ships 70+ built-in tools, but you are not limited to them. A custom tool is a declarative connector that turns any HTTP API into a first-class MCP tool. When it is enabled and available to a credential, your agent calls it exactly like a built-in tool — with tools/call.
What a custom tool is
A custom tool is a description of an HTTP request, not code. You define:
- The request — HTTP method, URL template, headers, and an optional body template.
- An input schema — a JSON Schema describing the arguments your agent supplies. apistash validates every call against it before making the request.
- An auth block — how apistash authenticates to the upstream API:
none,bearer, a customheader, orbasic.
When your agent calls the tool, apistash fills the templates with the validated arguments, injects the stored credentials, makes the request, and returns the response to the agent.
Your secrets stay server-side
The credential a custom tool uses to authenticate to its upstream API — an API key, bearer token, or basic-auth password — is encrypted at rest and injected only when the request is made. It is never returned by the API and never exposed to the AI agent; the model only ever sees the structured result.
Safe by construction
Custom-tool connectors may only call public HTTP/HTTPS endpoints. Requests to private, loopback, link-local, and cloud-metadata addresses are rejected, redirects are not followed, and response size and duration are capped.
How custom tools appear on MCP
Custom tools share the MCP tool namespace with built-in tools. Built-in tools are prefixed apistash/; custom tools are named by ownership space:
| Owner | Name on MCP |
|---|---|
| Your personal-in-org custom tools | me/{name} |
| Team-owned custom tools | {team}/{name} |
| Organization catalogue | {name} (unprefixed) |
Where custom tools come from
You can create and manage custom tools three ways: in the dashboard, through the REST API, or by letting an agent do it over MCP with the management tools (list_custom_tools, get_custom_tool, create_custom_tool, update_custom_tool, delete_custom_tool). A standalone personal credential uses bare names; an organization-scoped credential uses me/name for the represented member's private tools and <team>/name for a bound team. Bare organization-scoped names read from the organization catalogue, whose publication stays a deliberate dashboard action. Because a secret stays server-side, a tool an agent creates for an authenticated API remains switched off until a person adds its credential and enables it in the dashboard.
Which ones a credential can call is governed by the access model, and each plan caps how many you can create — see Plans & Limits.
Custom tools are visible only to a credential that carries the tools capability and is allowed to reach them by the access model.