Custom Tools API
A custom tool is your own tool on an MCP: a short Python script that calls the MCP's tools with default parameters and simple logic, such as listing recent emails and keeping only the unread ones with sender and subject. There is no model in the loop: the script chains calls, filters and trims results, and returns one answer.
Users and agents see a custom tool as one more tool of that MCP, on the MCP's own endpoint and in OneMCP. It works for remote, MCP Library and REST API MCPs. Every tool the script calls runs as the user who called the custom tool, with that user's connection to the MCP, and is logged.
Reading custom tools needs read. Creating, changing, deleting and test-running them needs tools:write (see scopes). Try every call in the MCP Management API playground.
What you authorize
The custom tool is what you authorize. Its own call goes through everything any tool call does:
- who can use it: turn it on or off and scope it to users or smart groups like any tool, or allow or deny it with a policy rule on its name;
- DLP on its arguments, and DLP on its result, which covers everything the script read;
- confirmation (approvals) and quotas;
- logging.
The calls its script makes skip the called tool's own checks: that tool's enabled setting, policy rules, quotas, DLP and confirmation do not apply when a custom tool calls it. Each of those calls is still logged, with the custom tool and the run id. So set the controls on the custom tool, and require confirmation on the custom tool itself when its script changes data.
A script can call any tool the MCP offers, including tools turned off in the MCP's settings (for everyone, or for some users or smart groups) and tools hidden by a discovery policy. It cannot call tools held for tool review, tools the upstream server no longer offers, other MCPs' tools or other custom tools.
Example: put a check in front of a tool
On a Box MCP, users should read files only from approved folders. Turn off read_file in the MCP's tool settings (or deny it with a policy rule), and add a custom tool read_file_safe that looks up the file's folder and calls read_file only for allowed folders. The allowed folder IDs go in fixed_args, so callers can neither see nor change them:
info = await get_file_info(file_id=args["file_id"])
folder_id = info["parent"]["id"]
if folder_id not in args["allowed_folder_ids"]:
result = {"allowed": False, "reason": "This file is not in an approved folder."}
else:
result = {"allowed": True, "content": await read_file(file_id=args["file_id"])}
result
with "input_schema": {"type": "object", "properties": {"file_id": {"type": "string"}}, "required": ["file_id"]} and "fixed_args": {"allowed_folder_ids": ["1234567890", "2345678901"]}. Users can no longer list or call read_file; they can call read_file_safe. Tool and argument names depend on the MCP: list the functions to see them.
A discovery policy only hides a tool from tool lists. A user who knows its name can still call it. To block a tool, turn it off in the MCP's settings or deny it with a policy rule.
Write the script
A custom tool is a definition plus a script:
The name goes in the path: a letter, then letters, digits, _ or -, at most 64 characters. Names starting with quilr_, and names ending in find_relevant_tools, call_tool or run_code (in any case), are reserved for gateway tools.
Schema rules
input_schema and output_schema are checked on every save (400 invalid_request otherwise):
- Write the schema out in full:
$ref,$id,$anchor,$dynamicRef,$dynamicAnchorand$recursiveRefare refused. $schemais allowed only at the top level.unevaluatedPropertiesis refused whenpatternPropertiesappears anywhere in the schema.- Each
patternandpatternPropertieskey is at most 512 characters.
When a call is checked against the schema, each regular expression match may take at most 1 second and the whole check at most 5 seconds. Call arguments are limited to 32 MB and 64 levels of nesting.
The script:
- Reads its arguments from
args: thedefaultswith what the caller sent on top, plus thefixed_args, which a caller cannot change. - Calls the MCP's tools. Each tool of the MCP is an async function (
await list_messages(folder="inbox")), andawait call_tool("list_messages", {...})calls any of them by its exact name, including tools turned off for users (see what you authorize). List the functions to see their Python signatures. - Gets each tool's result as its structured content, or its text parsed as JSON, or the text. On a REST API MCP each call returns
{"status", "headers", "body"}, with a JSON body already parsed. Servers built with FastMCP often return a plain-text answer as structured content{"result": "..."}, so readr["result"]there; a test run shows the shape. - Returns the value of its last top-level expression. Text is returned as is; anything else as JSON. A value computed inside an
if, loop ortryblock is not the last expression: assign it (out = ...) and end the script without. With anoutput_schema, the result must match it. A result over 80,000 characters is returned as an error, so filter or trim what the script returns. - Has
asyncio,datetime,json,math,reandtimealready imported. Importing them again is fine. - Handles failures with
ToolError: a failing tool call raises it, and the script can catch it. An uncaught error makes the custom tool return an error with the script's message. - Runs in a sandbox with no files, network or environment, and no imports beyond the sandbox's standard modules. It cannot call other custom tools or OneMCP's own tools, only the tools of its MCP.
print() output is shown only in test runs.
Each organization can run a limited number of custom tools at the same time. A run waits up to 10 seconds for a free slot; after that it fails as busy without running.
Example: unread email summary
This tool lists recent messages in a folder and returns only the unread ones, with sender and subject. folder and limit have defaults, so a client can call it with no arguments.
msgs = await list_messages(folder=args["folder"], top=args["limit"])
unread = [m for m in msgs["value"] if not m["isRead"]]
{"unread": len(unread), "items": [{"from": m["from"], "subject": m["subject"]} for m in unread]}
The commands use jq to read the version.
export GW='https://mcpgateway.quilr.ai' # your MCP Gateway host
export KEY='<management-key>' # needs read and tools:write
BASE="$GW/mcpgateway/management/v1"
MCP=a1b2c3d4
# The functions a script can call, with Python signatures
# ("hidden_from_clients": true marks tools turned off for everyone).
curl -s "$BASE/mcps/$MCP/custom-tools:functions" -H "Authorization: Bearer $KEY"
# Writes need the MCP's current version as If-Match.
VERSION=$(curl -s "$BASE/mcps/$MCP/custom-tools" -H "Authorization: Bearer $KEY" | jq -r .version)
curl -s -X PUT "$BASE/mcps/$MCP/custom-tools/recent_unread_summary" \
-H "Authorization: Bearer $KEY" -H "If-Match: \"$VERSION\"" -H 'Content-Type: application/json' \
-d '{
"description": "Unread emails in a folder: sender and subject only.",
"input_schema": {"type": "object", "properties": {
"folder": {"type": "string"}, "limit": {"type": "integer", "minimum": 1, "maximum": 50}}},
"defaults": {"folder": "inbox", "limit": 25},
"annotations": {"readOnlyHint": true},
"code": "msgs = await list_messages(folder=args[\"folder\"], top=args[\"limit\"])\nunread = [m for m in msgs[\"value\"] if not m[\"isRead\"]]\n{\"unread\": len(unread), \"items\": [{\"from\": m[\"from\"], \"subject\": m[\"subject\"]} for m in unread]}"
}'
# Try it as yourself (real calls), or try unsaved changes with "draft".
# The Idempotency-Key makes a retry return the stored answer instead of running again.
curl -s -X POST "$BASE/mcps/$MCP/custom-tools:test" -H "Authorization: Bearer $KEY" \
-H 'Idempotency-Key: try-unread-summary-1' \
-H 'Content-Type: application/json' -d '{"name": "recent_unread_summary", "arguments": {"limit": 10}}'
Save, change and delete
GET /mcps/{mcp_id}/custom-tools lists every custom tool of the MCP, enabled or not, with its script, uses_tools (the tools of the MCP it calls), status and listed_as (the tool definition clients receive). The response version is the If-Match value for the writes below (see versions and If-Match); a custom tool change changes the MCP's tool list, so it uses the MCP's version.
PUT /mcps/{mcp_id}/custom-tools/{name}saves the whole tool (201when new). Omitted optional fields take their defaults.PATCH /mcps/{mcp_id}/custom-tools/{name}changes the sent fields and keeps the rest. Send{"enabled": false}to hide the tool from clients, and{"enabled": true}to show it again.DELETE /mcps/{mcp_id}/custom-tools/{name}removes it.
Every save checks the definition: the script for syntax errors and for names it reads but never defines or imports, such as client.list() with no client (both 400 with the line), the schema and defaults, and the name, which must not be one of the MCP's own tools (409 tool_name_taken) or a reserved gateway tool name. Names the script calls that are not tools of the MCP, or that are waiting for tool review, come back as warnings; they do not block the save, because the MCP may list them again later. Tools turned off or hidden from users are tools of the MCP, so they are not warned about. Warnings are checked against the MCP's current tools on every read, so a tool the MCP has since dropped shows up there. tool_version grows by one on every save. Clients see a change within a few seconds, in their next tool list.
Version history
Every save is kept, up to the last 20.
GET /mcps/{mcp_id}/custom-tools/{name}/versionslists them, newest first, each withtool_version,saved_at,saved_by,code_sha256and the fulldefinition. It needsread.POST /mcps/{mcp_id}/custom-tools/{name}/restorewith{"version": 2}saves that definition again, as a new version. It needstools:writeandIf-Match, and the response carriesrestored_from. An unknown version answers404 custom_tool_version_not_found.
Validate
POST /mcps/{mcp_id}/custom-tools:validate with name and the definition runs every check a save runs and returns the normalized tool, including uses_tools, warnings and listed_as, without saving or running it. It needs only read.
List the functions a script can call
GET /mcps/{mcp_id}/custom-tools:functions returns one async function per tool a script can call: every tool the MCP offers now, including tools turned off for users, but not tools waiting for tool review. hidden_from_clients is true for a tool turned off in the MCP's settings for everyone: users cannot list or call it, custom tools can. Tools turned off only for some users or groups, or hidden by a policy, show false. Each function has a Python signature built from the tool's input schema (for example async def list_messages(folder: str = None, top: int = None)) and its summary. It also lists the globals every script has (args, call_tool, ToolError) and the run limits. Use it as the reference while you write the script.
Test-run
POST /mcps/{mcp_id}/custom-tools:test runs a custom tool and shows what happened:
{
"name": "recent_unread_summary",
"arguments": {"limit": 10},
"mocks": {"list_messages": {"value": [{"from": "ana@example.com", "subject": "Hi", "isRead": false}]}}
}
argumentsare sent as a client would send them.drafttries unsaved changes: its fields are merged over the saved tool, or form a whole new tool when nothing is saved undername. Errors in a draft name its field asbody.draft.<field>. A disabled tool can be tested; a disabled MCP answers409 mcp_disabledand nothing runs.mocksmaps exact tool names (thetoolfield ofcustom-tools:functions) to results (at most 50): those tools are not called, and the script gets the given value instead. Use it to try a script that changes data without changing it. A name the MCP does not offer is refused with400before anything runs, so a typo can never turn into a real call. The response lists the mocks the script actually called inmocked_tools.
The run is real. It runs as the key owner, with their own connection to the MCP, through the same path a client call takes, so the tools it calls (except mocked ones) have real effects and are logged. The checks of the custom tool's own call (policies, confirmation, DLP) apply as for a client call. Test with arguments that are safe to run, or mock the tools that change data.
Test runs are not available for OAuth passthrough MCPs, where each client brings its own token (409 test_run_unavailable); test those from a client.
Retry safely
Because a test run makes real calls, a failure without an answer can be ambiguous. 502 test_run_failed means the run failed before a result came back, and may_have_run says whether the tool could have run:
"may_have_run": true: the script started, or the run never recorded an answer. The tool may have run, and its calls may have changed data. The outcome is unknown."may_have_run": false: the run could not start, so nothing ran. Retrying is safe, and a retry with the sameIdempotency-Keyruns it.
An ambiguous failure looks like this:
{
"error": {
"code": "test_run_failed",
"message": "The test run failed before a result came back. The tool may have run, and its calls may have changed data: check the MCP's logs before running it again. Retrying with the same Idempotency-Key returns this answer; a new key runs the tool again",
"may_have_run": true
},
"request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f"
}
After an ambiguous failure, check the MCP's logs before you run it again: every tool call the script made is logged. To retry without running the tool twice, send an Idempotency-Key header with each test run (optional, 1 to 200 characters without control characters; a malformed key is 400 idempotency_key_required). Only runs whose script started are stored under the key:
A run is never given up while it is still running, however long it takes: the request running it renews its claim on the key every 10 seconds. A run whose gateway process stopped (no sign of life for 30 seconds) is given up, and its key answers 502 test_run_failed with "may_have_run": true, stored like any answer; the original request, if it still answers, returns the same. The outcome is unknown and the tool is never run again under that key. Check the logs, then use a new key if you still want to run it.
Approvals
Approvals happen on the custom tool's own call, before its script runs. The tools the script calls skip their own confirmation, so require confirmation on the custom tool, not on the tools it calls, when its script changes data. In a test run a pending approval shows as outcome: approval_required.
If the script returns while tool calls it started are still running, the answer carries the result with a warning and the unfinished_steps, so the caller can check their outcome before repeating them.
What users see
- A custom tool is listed with the MCP's other tools: on the MCP's own endpoint by its name, and in OneMCP with the MCP's prefix like its other tools. Discovery in OneMCP finds it too.
- Each default appears as
defaultin the tool's input schema, and arguments with a default are not required.fixed_argsare not shown. - With an
output_schema, clients get it asoutputSchemaand the result as structured content. - The MCP's per-tool settings (confirmation, enabled), tool visibility, policies, quotas and DLP apply to a custom tool by its name, its arguments and its result, like any tool. Use them to turn a custom tool off for some users or groups; use
enabled: falseto turn it off for everyone. They are not applied again to the tools it calls (see what you authorize). - Turning a tool off, or denying it with a policy rule, keeps users from calling it on every path, while custom tools can still call it.
- Each tool the script calls is logged as its own call, with the custom tool and the run id, so usage analytics show both the custom tool and the calls it made. Saves and deletes appear in the audit trail.
- If the MCP later gains a tool with the same name, that tool wins: clients see the MCP's tool, and the custom tool shows
status: shadoweduntil you rename or delete it.
Errors
See errors for the shared error shape and retry rules.
Endpoint reference
/mcps/{mcp_id}/custom-toolsList an MCP's custom tools
Every custom tool of the MCP, enabled or not, with its script, the tools it calls and how clients see it. `version` is the If-Match value for changes. MCPs of other tenants answer 404.
readPath, query & header parameters 1
mcp_id (path)stringrequiredMCP id (the `id` of an MCP, not its slug).
No request body.
curl --request GET \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/mcps/a1b2c3d4/custom-tools' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Scopes Try it in the playground
/mcps/{mcp_id}/custom-tools/{name}Delete a custom tool
Removes the tool; clients stop seeing it within seconds. Send the quoted `version` from the latest read in If-Match (428 when missing, 412 when stale).
tools:writePath, query & header parameters 3
mcp_id (path)stringrequiredMCP id (the `id` of an MCP, not its slug).
name (path)stringrequiredCustom tool name: a letter, then letters, digits, `_` or `-` (at most 64).
If-Match (header)stringrequiredQuoted `version` (ETag) from the latest read of this resource.
Full request body specification application/json
No body, or an empty JSON object.
Unknown fields are rejected in this object.
curl --request DELETE \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/mcps/a1b2c3d4/custom-tools/recent_unread_summary' \
--header 'Authorization: Bearer <management-key>' \
--header 'If-Match: "r4"'
Authentication, errors & retry rules Scopes Try it in the playground
/mcps/{mcp_id}/custom-tools/{name}Read a custom tool
One custom tool. 404 `custom_tool_not_found`. MCPs of other tenants answer 404.
readPath, query & header parameters 2
mcp_id (path)stringrequiredMCP id (the `id` of an MCP, not its slug).
name (path)stringrequiredCustom tool name: a letter, then letters, digits, `_` or `-` (at most 64).
No request body.
curl --request GET \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/mcps/a1b2c3d4/custom-tools/recent_unread_summary' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Scopes Try it in the playground
/mcps/{mcp_id}/custom-tools/{name}Change a custom tool
Changes the sent fields and keeps the rest, for example `{"enabled": false}` to hide the tool. 404 `custom_tool_not_found`. Send the quoted `version` from the latest read in If-Match (428 when missing, 412 when stale).
tools:writePath, query & header parameters 3
mcp_id (path)stringrequiredMCP id (the `id` of an MCP, not its slug).
name (path)stringrequiredCustom tool name: a letter, then letters, digits, `_` or `-` (at most 64).
If-Match (header)stringrequiredQuoted `version` (ETag) from the latest read of this resource.
Full request body specification application/json
Fields to change; the rest keep their saved values.
annotationsobjectoptionalTool hints for clients: `title` and the booleans `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`. `title` is at most 200 characters.
codestringoptionalPython script, at most 65536 bytes as UTF-8 (`maxLength` counts characters, so a script with non-ASCII text can be refused below it). `args` holds the arguments (defaults plus what the caller sent). Each tool of the MCP is an async function (`await list_messages(folder="inbox")`), and `await call_tool("<tool name>", {...})` calls any of them by name. This includes tools turned off for users (in the MCP's settings or by a policy) and tools hidden from tool lists. These calls skip the called tool's own enabled setting, policies, quotas, DLP and approvals; the custom tool's own call carries those checks. Tools waiting for tool review, tools the MCP no longer offers, other MCPs' tools and other custom tools cannot be called. The value of the last top-level expression is the tool's result (assign a value computed inside an `if` or loop and end with it). `asyncio`, `datetime`, `json`, `math`, `re` and `time` are already imported. No files, network, environment or imports beyond the sandbox's standard modules. A script that reads a name it never defines or imports is refused on save (400 with the `line`).
defaultsobjectoptionalDefault argument values, at most 16 KiB. Clients see them as `default` and do not have to send them; values a call sends replace them.
descriptionstringoptionalWhat the tool does and when to use it; models read this to pick the tool.
enabledbooleanoptionalfalse hides the tool from clients (default true).
fixed_argsobjectoptionalValues the script always gets in `args`, hidden from clients and never replaced by what a caller sends (for example a fixed project id). Names must not be input_schema properties. At most 16 KiB. Not for secrets: they are returned by reads; keep credentials in the MCP's upstream credentials.
input_schemaobjectoptionalJSON Schema of the arguments: `type: object` with typed top-level `properties` (string, number, integer, boolean, array, object), `required` and `additionalProperties` (default false). Allowed top-level keys: `type`, `properties`, `required`, `additionalProperties`, `description`, `$schema` and `title` (the last two are dropped on save). Property names are identifiers (letters, digits and _, at most 64 characters) and every property needs a `type`. At most 50 properties and 16 KiB. No `$ref`, `$id`, `$anchor`, `$dynamicRef`, `$dynamicAnchor` or `$recursiveRef`; `$schema` only at the top level; `unevaluatedProperties` is refused when `patternProperties` appears anywhere in the schema. Each `pattern` or `patternProperties` key is at most 512 characters. When a call is checked, a regex match that takes over 1 s, or a check that takes over 5 s, fails the call. Call arguments are limited to 32 MB and 64 levels of nesting.
limitsobjectoptional`timeout_s` (1 to 60, default 60) and `max_tool_calls` (1 to 50, default 50) per run.
output_schemaobject | nulloptionalOptional JSON Schema (`type: object`) of the result. Clients receive it as the tool's outputSchema and the result as structured content; a result that does not match is returned as an error. At most 16 KiB. The same rules as `input_schema` apply to references, `$schema`, `unevaluatedProperties`, pattern length and match time.
Unknown fields are rejected in this object.
curl --request PATCH \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/mcps/a1b2c3d4/custom-tools/recent_unread_summary' \
--header 'Authorization: Bearer <management-key>' \
--header 'If-Match: "r4"' \
--header 'Content-Type: application/json' \
--data '{
"enabled": false
}'
Authentication, errors & retry rules Scopes Try it in the playground
/mcps/{mcp_id}/custom-tools/{name}Create or replace a custom tool
Saves the whole tool under `name` (201 when new). The name must not be one the MCP's own tools use (409 `tool_name_taken`) or a gateway tool name. The script is checked for syntax errors and for names it reads but never defines or imports (400 with the `line`); names it calls that are not tools of the MCP come back as `warnings`. An MCP can have up to 50 custom tools (409 `custom_tool_limit`). Clients see the change within seconds. Send the quoted `version` from the latest read in If-Match (428 when missing, 412 when stale).
tools:writePath, query & header parameters 3
mcp_id (path)stringrequiredMCP id (the `id` of an MCP, not its slug).
name (path)stringrequiredCustom tool name: a letter, then letters, digits, `_` or `-` (at most 64).
If-Match (header)stringrequiredQuoted `version` (ETag) from the latest read of this resource.
Full request body specification application/json
The whole tool. Omitted optional fields take their defaults.
annotationsobjectoptionalTool hints for clients: `title` and the booleans `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`. `title` is at most 200 characters.
codestringrequiredPython script, at most 65536 bytes as UTF-8 (`maxLength` counts characters, so a script with non-ASCII text can be refused below it). `args` holds the arguments (defaults plus what the caller sent). Each tool of the MCP is an async function (`await list_messages(folder="inbox")`), and `await call_tool("<tool name>", {...})` calls any of them by name. This includes tools turned off for users (in the MCP's settings or by a policy) and tools hidden from tool lists. These calls skip the called tool's own enabled setting, policies, quotas, DLP and approvals; the custom tool's own call carries those checks. Tools waiting for tool review, tools the MCP no longer offers, other MCPs' tools and other custom tools cannot be called. The value of the last top-level expression is the tool's result (assign a value computed inside an `if` or loop and end with it). `asyncio`, `datetime`, `json`, `math`, `re` and `time` are already imported. No files, network, environment or imports beyond the sandbox's standard modules. A script that reads a name it never defines or imports is refused on save (400 with the `line`).
defaultsobjectoptionalDefault argument values, at most 16 KiB. Clients see them as `default` and do not have to send them; values a call sends replace them.
descriptionstringrequiredWhat the tool does and when to use it; models read this to pick the tool.
enabledbooleanoptionalfalse hides the tool from clients (default true).
fixed_argsobjectoptionalValues the script always gets in `args`, hidden from clients and never replaced by what a caller sends (for example a fixed project id). Names must not be input_schema properties. At most 16 KiB. Not for secrets: they are returned by reads; keep credentials in the MCP's upstream credentials.
input_schemaobjectoptionalJSON Schema of the arguments: `type: object` with typed top-level `properties` (string, number, integer, boolean, array, object), `required` and `additionalProperties` (default false). Allowed top-level keys: `type`, `properties`, `required`, `additionalProperties`, `description`, `$schema` and `title` (the last two are dropped on save). Property names are identifiers (letters, digits and _, at most 64 characters) and every property needs a `type`. At most 50 properties and 16 KiB. No `$ref`, `$id`, `$anchor`, `$dynamicRef`, `$dynamicAnchor` or `$recursiveRef`; `$schema` only at the top level; `unevaluatedProperties` is refused when `patternProperties` appears anywhere in the schema. Each `pattern` or `patternProperties` key is at most 512 characters. When a call is checked, a regex match that takes over 1 s, or a check that takes over 5 s, fails the call. Call arguments are limited to 32 MB and 64 levels of nesting.
limitsobjectoptional`timeout_s` (1 to 60, default 60) and `max_tool_calls` (1 to 50, default 50) per run.
output_schemaobject | nulloptionalOptional JSON Schema (`type: object`) of the result. Clients receive it as the tool's outputSchema and the result as structured content; a result that does not match is returned as an error. At most 16 KiB. The same rules as `input_schema` apply to references, `$schema`, `unevaluatedProperties`, pattern length and match time.
Unknown fields are rejected in this object.
curl --request PUT \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/mcps/a1b2c3d4/custom-tools/recent_unread_summary' \
--header 'Authorization: Bearer <management-key>' \
--header 'If-Match: "r4"' \
--header 'Content-Type: application/json' \
--data '{
"annotations": {
"readOnlyHint": true
},
"code": "msgs = await list_messages(folder=args[\"folder\"], top=args[\"limit\"])\nunread = [m for m in msgs[\"value\"] if not m[\"isRead\"]]\n{\"unread\": len(unread), \"items\": [{\"from\": m[\"from\"], \"subject\": m[\"subject\"]} for m in unread]}",
"defaults": {
"folder": "inbox",
"limit": 25
},
"description": "Unread emails in a folder: sender and subject only. Use to brief the user on new mail.",
"input_schema": {
"additionalProperties": false,
"properties": {
"folder": {
"type": "string"
},
"limit": {
"maximum": 50,
"minimum": 1,
"type": "integer"
}
},
"type": "object"
}
}'
Authentication, errors & retry rules Scopes Try it in the playground
/mcps/{mcp_id}/custom-tools/{name}/restoreRestore an earlier version
Saves an earlier definition from the history again, as a new version. 404 `custom_tool_version_not_found`. Send the quoted `version` from the latest read in If-Match (428 when missing, 412 when stale).
tools:writePath, query & header parameters 3
mcp_id (path)stringrequiredMCP id (the `id` of an MCP, not its slug).
name (path)stringrequiredCustom tool name: a letter, then letters, digits, `_` or `-` (at most 64).
If-Match (header)stringrequiredQuoted `version` (ETag) from the latest read of this resource.
Full request body specification application/json
versionintegerrequiredA `tool_version` from the history.
Unknown fields are rejected in this object.
curl --request POST \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/mcps/a1b2c3d4/custom-tools/recent_unread_summary/restore' \
--header 'Authorization: Bearer <management-key>' \
--header 'If-Match: "r4"' \
--header 'Content-Type: application/json' \
--data '{
"version": 2
}'
Authentication, errors & retry rules Scopes Try it in the playground
/mcps/{mcp_id}/custom-tools/{name}/versionsList a custom tool's saved versions
The last 20 saved definitions of the tool, newest first, with who saved each and when.
readPath, query & header parameters 2
mcp_id (path)stringrequiredMCP id (the `id` of an MCP, not its slug).
name (path)stringrequiredCustom tool name: a letter, then letters, digits, `_` or `-` (at most 64).
No request body.
curl --request GET \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/mcps/a1b2c3d4/custom-tools/recent_unread_summary/versions' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Scopes Try it in the playground
/mcps/{mcp_id}/custom-tools:functionsList the functions a script can call
One async function per tool a script can call: every tool the MCP offers now, including tools turned off for users (`hidden_from_clients`), but not tools waiting for tool review. Each has a Python signature built from the tool's input schema. Also the globals every script has (`args`, `call_tool`, `ToolError`) and the run limits.
readPath, query & header parameters 1
mcp_id (path)stringrequiredMCP id (the `id` of an MCP, not its slug).
No request body.
curl --request GET \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/mcps/a1b2c3d4/custom-tools:functions' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Scopes Try it in the playground
/mcps/{mcp_id}/custom-tools:testTest-run a custom tool
Runs the saved tool, or `draft` changes over it (or a new tool not saved yet), as the key owner with their own connection to the MCP, through the same path a client call takes. The tools it calls are real calls with real effects and are logged; the checks of the custom tool's own call (policies, approvals, DLP) apply as for a client call. Returns what a client would get plus each call made, print() output and the error. A disabled tool can be tested. 409 `test_run_unavailable` for MCPs where each user signs in with their own token (OAuth passthrough); 409 `mcp_disabled` when the MCP is disabled (nothing ran). `mocks` names must be tools the MCP offers (400 otherwise, before anything runs); `mocked_tools` lists the mocks the script actually called. **Ambiguous failures.** 502 `test_run_failed` with `error.may_have_run`: true means the run failed after the script started: the tool may have run, and its calls may have changed data. Check the MCP's logs before running it again. `may_have_run`: false means it failed before the script started; nothing ran. **Retries.** Send an `Idempotency-Key` to retry safely. When the script started (a result, a script error or the ambiguous 502), the same key and body within 24 hours return that stored answer instead of running again. When the tool certainly did not run (custom tools busy, invalid arguments, refused before the script, unknown tool or MCP, a failure before dispatch), nothing is stored and a retry with the same key runs. Requests with one key that arrive while it runs wait for its answer, or get 409 `test_run_in_progress` (retry after `Retry-After`); a run is never given up while it is still running, however long it takes. A run whose gateway process stopped (no sign of life for 30 seconds) becomes a stored 502 `test_run_failed` with `may_have_run`: true, and the original request, if it still answers, returns that same answer; it is never run again under that key. A different body under the key is 409 `idempotency_conflict`; a new key runs the tool again.
tools:writePath, query & header parameters 2
mcp_id (path)stringrequiredMCP id (the `id` of an MCP, not its slug).
Idempotency-Key (header)stringoptionalOptional client-chosen token (1 to 200 characters). With it, the same token and body within 24 hours returns the stored answer (a result or a failure) instead of running again; a different body under the same token is 409 `idempotency_conflict`.
Full request body specification application/json
argumentsobjectoptionalArguments, as a client would send them.
draftobjectoptionalUnsaved changes to try: merged over the saved tool, or a whole new tool when none is saved under `name`.
Object fields
annotationsobjectoptionalTool hints for clients: `title` and the booleans `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`. `title` is at most 200 characters.
codestringoptionalPython script, at most 65536 bytes as UTF-8 (`maxLength` counts characters, so a script with non-ASCII text can be refused below it). `args` holds the arguments (defaults plus what the caller sent). Each tool of the MCP is an async function (`await list_messages(folder="inbox")`), and `await call_tool("<tool name>", {...})` calls any of them by name. This includes tools turned off for users (in the MCP's settings or by a policy) and tools hidden from tool lists. These calls skip the called tool's own enabled setting, policies, quotas, DLP and approvals; the custom tool's own call carries those checks. Tools waiting for tool review, tools the MCP no longer offers, other MCPs' tools and other custom tools cannot be called. The value of the last top-level expression is the tool's result (assign a value computed inside an `if` or loop and end with it). `asyncio`, `datetime`, `json`, `math`, `re` and `time` are already imported. No files, network, environment or imports beyond the sandbox's standard modules. A script that reads a name it never defines or imports is refused on save (400 with the `line`).
defaultsobjectoptionalDefault argument values, at most 16 KiB. Clients see them as `default` and do not have to send them; values a call sends replace them.
descriptionstringoptionalWhat the tool does and when to use it; models read this to pick the tool.
enabledbooleanoptionalfalse hides the tool from clients (default true).
fixed_argsobjectoptionalValues the script always gets in `args`, hidden from clients and never replaced by what a caller sends (for example a fixed project id). Names must not be input_schema properties. At most 16 KiB. Not for secrets: they are returned by reads; keep credentials in the MCP's upstream credentials.
input_schemaobjectoptionalJSON Schema of the arguments: `type: object` with typed top-level `properties` (string, number, integer, boolean, array, object), `required` and `additionalProperties` (default false). Allowed top-level keys: `type`, `properties`, `required`, `additionalProperties`, `description`, `$schema` and `title` (the last two are dropped on save). Property names are identifiers (letters, digits and _, at most 64 characters) and every property needs a `type`. At most 50 properties and 16 KiB. No `$ref`, `$id`, `$anchor`, `$dynamicRef`, `$dynamicAnchor` or `$recursiveRef`; `$schema` only at the top level; `unevaluatedProperties` is refused when `patternProperties` appears anywhere in the schema. Each `pattern` or `patternProperties` key is at most 512 characters. When a call is checked, a regex match that takes over 1 s, or a check that takes over 5 s, fails the call. Call arguments are limited to 32 MB and 64 levels of nesting.
limitsobjectoptional`timeout_s` (1 to 60, default 60) and `max_tool_calls` (1 to 50, default 50) per run.
output_schemaobject | nulloptionalOptional JSON Schema (`type: object`) of the result. Clients receive it as the tool's outputSchema and the result as structured content; a result that does not match is returned as an error. At most 16 KiB. The same rules as `input_schema` apply to references, `$schema`, `unevaluatedProperties`, pattern length and match time.
Unknown fields are rejected in this object.
mocksobjectoptionalExact tool name (the `tool` field of custom-tools:functions) to result: these tools are not called, the script gets the given value instead. Use it to try a script that changes data without changing it. A name the MCP does not offer is refused with 400 before anything runs.
namestringrequiredUnknown fields are rejected in this object.
curl --request POST \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/mcps/a1b2c3d4/custom-tools:test' \
--header 'Authorization: Bearer <management-key>' \
--header 'Content-Type: application/json' \
--data '{
"arguments": {
"limit": 10
},
"name": "recent_unread_summary"
}'
Authentication, errors & retry rules Scopes Try it in the playground
/mcps/{mcp_id}/custom-tools:validateCheck a custom tool definition
Runs every check a save runs and returns the normalized tool, without saving or running it.
readPath, query & header parameters 1
mcp_id (path)stringrequiredMCP id (the `id` of an MCP, not its slug).
Full request body specification application/json
A definition to check without saving.
annotationsobjectoptionalTool hints for clients: `title` and the booleans `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`. `title` is at most 200 characters.
codestringrequiredPython script, at most 65536 bytes as UTF-8 (`maxLength` counts characters, so a script with non-ASCII text can be refused below it). `args` holds the arguments (defaults plus what the caller sent). Each tool of the MCP is an async function (`await list_messages(folder="inbox")`), and `await call_tool("<tool name>", {...})` calls any of them by name. This includes tools turned off for users (in the MCP's settings or by a policy) and tools hidden from tool lists. These calls skip the called tool's own enabled setting, policies, quotas, DLP and approvals; the custom tool's own call carries those checks. Tools waiting for tool review, tools the MCP no longer offers, other MCPs' tools and other custom tools cannot be called. The value of the last top-level expression is the tool's result (assign a value computed inside an `if` or loop and end with it). `asyncio`, `datetime`, `json`, `math`, `re` and `time` are already imported. No files, network, environment or imports beyond the sandbox's standard modules. A script that reads a name it never defines or imports is refused on save (400 with the `line`).
defaultsobjectoptionalDefault argument values, at most 16 KiB. Clients see them as `default` and do not have to send them; values a call sends replace them.
descriptionstringrequiredWhat the tool does and when to use it; models read this to pick the tool.
enabledbooleanoptionalfalse hides the tool from clients (default true).
fixed_argsobjectoptionalValues the script always gets in `args`, hidden from clients and never replaced by what a caller sends (for example a fixed project id). Names must not be input_schema properties. At most 16 KiB. Not for secrets: they are returned by reads; keep credentials in the MCP's upstream credentials.
input_schemaobjectoptionalJSON Schema of the arguments: `type: object` with typed top-level `properties` (string, number, integer, boolean, array, object), `required` and `additionalProperties` (default false). Allowed top-level keys: `type`, `properties`, `required`, `additionalProperties`, `description`, `$schema` and `title` (the last two are dropped on save). Property names are identifiers (letters, digits and _, at most 64 characters) and every property needs a `type`. At most 50 properties and 16 KiB. No `$ref`, `$id`, `$anchor`, `$dynamicRef`, `$dynamicAnchor` or `$recursiveRef`; `$schema` only at the top level; `unevaluatedProperties` is refused when `patternProperties` appears anywhere in the schema. Each `pattern` or `patternProperties` key is at most 512 characters. When a call is checked, a regex match that takes over 1 s, or a check that takes over 5 s, fails the call. Call arguments are limited to 32 MB and 64 levels of nesting.
limitsobjectoptional`timeout_s` (1 to 60, default 60) and `max_tool_calls` (1 to 50, default 50) per run.
namestringrequiredoutput_schemaobject | nulloptionalOptional JSON Schema (`type: object`) of the result. Clients receive it as the tool's outputSchema and the result as structured content; a result that does not match is returned as an error. At most 16 KiB. The same rules as `input_schema` apply to references, `$schema`, `unevaluatedProperties`, pattern length and match time.
Unknown fields are rejected in this object.
curl --request POST \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/mcps/a1b2c3d4/custom-tools:validate' \
--header 'Authorization: Bearer <management-key>' \
--header 'Content-Type: application/json' \
--data '{
"annotations": {
"readOnlyHint": true
},
"code": "msgs = await list_messages(folder=args[\"folder\"], top=args[\"limit\"])\nunread = [m for m in msgs[\"value\"] if not m[\"isRead\"]]\n{\"unread\": len(unread), \"items\": [{\"from\": m[\"from\"], \"subject\": m[\"subject\"]} for m in unread]}",
"defaults": {
"folder": "inbox",
"limit": 25
},
"description": "Unread emails in a folder: sender and subject only. Use to brief the user on new mail.",
"input_schema": {
"additionalProperties": false,
"properties": {
"folder": {
"type": "string"
},
"limit": {
"maximum": 50,
"minimum": 1,
"type": "integer"
}
},
"type": "object"
},
"name": "recent_unread_summary"
}'
Authentication, errors & retry rules Scopes Try it in the playground