Skip to main content

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.

Hiding a tool from discovery does not block it

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:

FieldMeaning
descriptionWhat the tool does and when to use it. Models read it to pick the tool. Required, at most 2,000 characters.
input_schemaJSON Schema of the arguments: type: object with top-level properties, required and additionalProperties (default false). The only other top-level keys allowed are description, title and $schema; title and $schema are not saved. Property names are identifiers (letters, digits and _, at most 64 characters) and every property needs a type (string, number, integer, boolean, array, object). At most 50 properties and 16 KiB. See schema rules.
defaultsDefault argument values, each naming an input_schema property and matching its schema. Clients see each one as default in the tool's schema and do not have to send it. At most 16 KiB.
fixed_argsValues the script always gets in args, hidden from clients and never replaced by what a caller sends, for example a fixed project id. Names are identifiers and must not be input_schema properties. At most 16 KiB. Not for secrets: reads return them, so keep credentials in the MCP's upstream credentials.
output_schemaOptional JSON Schema (type: object) of the result, at most 16 KiB. 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. The schema rules apply.
codeThe Python script, at most 64 KiB (UTF-8). Required.
enabledfalse hides the tool from clients. Default true.
annotationsHints for clients: title (at most 200 characters) and the booleans readOnlyHint, destructiveHint, idempotentHint, openWorldHint.
limitstimeout_s (1 to 60) and max_tool_calls (1 to 50) per run, to lower the defaults for one tool. The other limits cannot be changed per tool.

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, $dynamicAnchor and $recursiveRef are refused.
  • $schema is allowed only at the top level.
  • unevaluatedProperties is refused when patternProperties appears anywhere in the schema.
  • Each pattern and patternProperties key 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: the defaults with what the caller sent on top, plus the fixed_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")), and await 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 read r["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 or try block is not the last expression: assign it (out = ...) and end the script with out. With an output_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, re and time already 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.
LimitValue
Run time60 seconds
Tool calls per run50
Script size64 KiB (UTF-8)
Result size80,000 characters
Custom tools per MCP50

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 (201 when 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}/versions lists them, newest first, each with tool_version, saved_at, saved_by, code_sha256 and the full definition. It needs read.
  • POST /mcps/{mcp_id}/custom-tools/{name}/restore with {"version": 2} saves that definition again, as a new version. It needs tools:write and If-Match, and the response carries restored_from. An unknown version answers 404 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}]}}
}
  • arguments are sent as a client would send them.
  • draft tries unsaved changes: its fields are merged over the saved tool, or form a whole new tool when nothing is saved under name. Errors in a draft name its field as body.draft.<field>. A disabled tool can be tested; a disabled MCP answers 409 mcp_disabled and nothing runs.
  • mocks maps exact tool names (the tool field of custom-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 with 400 before anything runs, so a typo can never turn into a real call. The response lists the mocks the script actually called in mocked_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.

Response fieldMeaning
outcomeok, error (the script or a tool failed), approval_required (the call is waiting for approval) or refused (the tool did not run: hidden from the key owner, blocked by a policy, no connection, invalid arguments, or no free run slot). With refused, run is null.
client_resultThe MCP result a client would get.
mocked_toolsThe tools the script called that were answered from mocks instead of being called.
errorThe error message, when there is one.
run.callsEach tool call the script made, in order, with ok and the time it took.
run.resultThe script's result.
run.logsprint() output.
run.error_kindscript_error, timeout, memory, max_tool_calls, result_too_large (over 80,000 characters), output_schema (the result does not match it), runner_error (the sandbox failed) or approval_required.

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 same Idempotency-Key runs 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:

SituationResult
Same key and same body within 24 hours, after the script startedThe stored answer is returned and the tool does not run again: the result (including a script error) or the ambiguous 502 above. A stored answer is returned even if the MCP was removed since.
Same key after a run that certainly did not run the toolNothing was stored, so the retry runs the tool. This covers custom tools being busy, no script worker being available, arguments that do not match the schema, a refusal before the script, an unknown tool or MCP (404) and a failure before dispatch (502 with "may_have_run": false).
Same key while the first run is still goingThe request waits for the run on the same gateway process and gets its answer. A request that reaches another process gets 409 test_run_in_progress with operation_id; retry after Retry-After (1 second).
Same key with a different body409 idempotency_conflict.
A new keyThe tool runs again. Against an MCP that was removed, 404 not_found.
Same key after 24 hours409 idempotency_replay_expired; use a new 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 default in the tool's input schema, and arguments with a default are not required. fixed_args are not shown.
  • With an output_schema, clients get it as outputSchema and 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: false to 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: shadowed until you rename or delete it.

Errors​

StatusCodeMeaning
400invalid_requestThe definition is invalid, for example a schema that uses $ref, $id or anchors. error.fields names the field; a syntax error or an undefined name in the script also carries line. Also a mocks name the MCP does not offer (body.mocks).
400idempotency_key_requiredThe test run's Idempotency-Key is over 200 characters or has control characters.
404custom_tool_not_foundNo custom tool with this name on the MCP.
404custom_tool_version_not_foundNo saved version with this tool_version in the tool's history.
409tool_name_takenOne of the MCP's own tools already uses this name.
409custom_tool_limitThe MCP already has 50 custom tools.
409test_run_unavailableThe MCP is an OAuth passthrough MCP: each client brings its own token, so a test run cannot use the key owner's connection.
409mcp_disabledTest run on a disabled MCP: nothing ran. Enable the MCP and retry (the same Idempotency-Key runs it).
409test_run_in_progressA test run with this Idempotency-Key is still running (operation_id, Retry-After). See retry safely.
409idempotency_conflictThe Idempotency-Key was used for a test run with a different body.
412version_conflictIf-Match is stale: the MCP changed since you read it. Read the list again and retry.
428precondition_requiredIf-Match missing on a write.
502test_run_failedThe test run failed before a result came back. With "may_have_run": true the tool may have run: check the logs; the same Idempotency-Key returns this stored answer. With "may_have_run": false nothing ran: retry, with the same key or a new one.

See errors for the shared error shape and retry rules.

Endpoint reference​

GET/mcps/{mcp_id}/custom-tools

List 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.

REQUIRESread
Path, query & header parameters 1
mcp_id (path)stringrequired

MCP 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

DELETE/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).

REQUIREStools:write
Path, query & header parameters 3
mcp_id (path)stringrequired

MCP id (the `id` of an MCP, not its slug).

name (path)stringrequired

Custom tool name: a letter, then letters, digits, `_` or `-` (at most 64).

If-Match (header)stringrequired

Quoted `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

GET/mcps/{mcp_id}/custom-tools/{name}

Read a custom tool

One custom tool. 404 `custom_tool_not_found`. MCPs of other tenants answer 404.

REQUIRESread
Path, query & header parameters 2
mcp_id (path)stringrequired

MCP id (the `id` of an MCP, not its slug).

name (path)stringrequired

Custom 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

PATCH/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).

REQUIREStools:write
Path, query & header parameters 3
mcp_id (path)stringrequired

MCP id (the `id` of an MCP, not its slug).

name (path)stringrequired

Custom tool name: a letter, then letters, digits, `_` or `-` (at most 64).

If-Match (header)stringrequired

Quoted `version` (ETag) from the latest read of this resource.

Full request body specification application/json

Fields to change; the rest keep their saved values.

annotationsobjectoptional

Tool hints for clients: `title` and the booleans `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`. `title` is at most 200 characters.

codestringoptional

Python 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`).

min length: 1max length: 65536
defaultsobjectoptional

Default argument values, at most 16 KiB. Clients see them as `default` and do not have to send them; values a call sends replace them.

descriptionstringoptional

What the tool does and when to use it; models read this to pick the tool.

min length: 1max length: 2000
enabledbooleanoptional

false hides the tool from clients (default true).

fixed_argsobjectoptional

Values 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_schemaobjectoptional

JSON 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 | nulloptional

Optional 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

PUT/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).

REQUIREStools:write
Path, query & header parameters 3
mcp_id (path)stringrequired

MCP id (the `id` of an MCP, not its slug).

name (path)stringrequired

Custom tool name: a letter, then letters, digits, `_` or `-` (at most 64).

If-Match (header)stringrequired

Quoted `version` (ETag) from the latest read of this resource.

Full request body specification application/json

The whole tool. Omitted optional fields take their defaults.

annotationsobjectoptional

Tool hints for clients: `title` and the booleans `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`. `title` is at most 200 characters.

codestringrequired

Python 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`).

min length: 1max length: 65536
defaultsobjectoptional

Default argument values, at most 16 KiB. Clients see them as `default` and do not have to send them; values a call sends replace them.

descriptionstringrequired

What the tool does and when to use it; models read this to pick the tool.

min length: 1max length: 2000
enabledbooleanoptional

false hides the tool from clients (default true).

fixed_argsobjectoptional

Values 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_schemaobjectoptional

JSON 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 | nulloptional

Optional 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

POST/mcps/{mcp_id}/custom-tools/{name}/restore

Restore 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).

REQUIREStools:write
Path, query & header parameters 3
mcp_id (path)stringrequired

MCP id (the `id` of an MCP, not its slug).

name (path)stringrequired

Custom tool name: a letter, then letters, digits, `_` or `-` (at most 64).

If-Match (header)stringrequired

Quoted `version` (ETag) from the latest read of this resource.

Full request body specification application/json

versionintegerrequired

A `tool_version` from the history.

min: 1

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

GET/mcps/{mcp_id}/custom-tools/{name}/versions

List a custom tool's saved versions

The last 20 saved definitions of the tool, newest first, with who saved each and when.

REQUIRESread
Path, query & header parameters 2
mcp_id (path)stringrequired

MCP id (the `id` of an MCP, not its slug).

name (path)stringrequired

Custom 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

GET/mcps/{mcp_id}/custom-tools:functions

List 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.

REQUIRESread
Path, query & header parameters 1
mcp_id (path)stringrequired

MCP 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

POST/mcps/{mcp_id}/custom-tools:test

Test-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.

REQUIREStools:write
Path, query & header parameters 2
mcp_id (path)stringrequired

MCP id (the `id` of an MCP, not its slug).

Idempotency-Key (header)stringoptional

Optional 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`.

min length: 1max length: 200
Full request body specification application/json

argumentsobjectoptional

Arguments, as a client would send them.

draftobjectoptional

Unsaved changes to try: merged over the saved tool, or a whole new tool when none is saved under `name`.

Object fields
annotationsobjectoptional

Tool hints for clients: `title` and the booleans `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`. `title` is at most 200 characters.

codestringoptional

Python 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`).

min length: 1max length: 65536
defaultsobjectoptional

Default argument values, at most 16 KiB. Clients see them as `default` and do not have to send them; values a call sends replace them.

descriptionstringoptional

What the tool does and when to use it; models read this to pick the tool.

min length: 1max length: 2000
enabledbooleanoptional

false hides the tool from clients (default true).

fixed_argsobjectoptional

Values 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_schemaobjectoptional

JSON 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 | nulloptional

Optional 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.

mocksobjectoptional

Exact 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.

namestringrequired
max length: 64

Unknown 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

POST/mcps/{mcp_id}/custom-tools:validate

Check a custom tool definition

Runs every check a save runs and returns the normalized tool, without saving or running it.

REQUIRESread
Path, query & header parameters 1
mcp_id (path)stringrequired

MCP id (the `id` of an MCP, not its slug).

Full request body specification application/json

A definition to check without saving.

annotationsobjectoptional

Tool hints for clients: `title` and the booleans `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`. `title` is at most 200 characters.

codestringrequired

Python 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`).

min length: 1max length: 65536
defaultsobjectoptional

Default argument values, at most 16 KiB. Clients see them as `default` and do not have to send them; values a call sends replace them.

descriptionstringrequired

What the tool does and when to use it; models read this to pick the tool.

min length: 1max length: 2000
enabledbooleanoptional

false hides the tool from clients (default true).

fixed_argsobjectoptional

Values 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_schemaobjectoptional

JSON 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.

namestringrequired
max length: 64
output_schemaobject | nulloptional

Optional 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