Hooks API
Check tool calls with your own API. A hook sends each tool call to an HTTPS endpoint you run. Your endpoint answers allow, flag or block: before the tool runs, to stop an action, or after it runs, to stop the AI from seeing the result. Your rules stay on your own server. An export hook instead sends finished tool calls to your endpoint in batches, for example to your SIEM.
Hooks are created and changed only through the Management API. The console shows them read-only: go to Settings > AI Gateway > MCP Gateway > Management API and click Configured hooks. Reading hooks needs read; creating, changing, deleting and testing them needs hooks:write (see scopes). You can run the management-key calls in the MCP Management API playground. The administrator route that lists an organization's hooks (GET /mcpgateway/management-admin/v1/tenants/{tenant_id}/hooks) needs a tenant administrator token and is reference only (see Administration endpoints).
DLP and post_call. Without the Policy Engine, response DLP runs before the post_call hook, so the hook gets the redacted result. With the Policy Engine on, response DLP runs after the post_call hook, so the hook gets the tool result before redaction (send.result is true by default on post_call). Set send.result to false if your endpoint must not receive it.
Hooks run on every tool call through the MCP's own endpoint and through OneMCP, and on a custom tool's own call. The calls a custom tool's script makes do not run hooks.
Example
Block the AI from deleting Jira issues. The hook runs only on the Jira MCP's delete_issue tool:
curl -X POST https://mcpgateway.quilr.ai/mcpgateway/management/v1/hooks \
-H "Authorization: Bearer $QUILR_MCP_MANAGEMENT_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "ACME tool check",
"stage": "pre_call",
"all_mcps": false,
"scope": {"mcp_ids": ["a1b2c3d4"], "tools": ["delete_issue"]},
"endpoint": {
"url": "https://hooks.example.com/mcp/check",
"timeout_ms": 1500,
"on_failure": "block",
"auth": {"type": "bearer", "secret": "token"},
"signing": {"secret": "signing_key"}
},
"secrets": {"token": "<your token>", "signing_key": "<your signing key>"}
}'
Replace a1b2c3d4 with the Jira MCP's id from GET /mcps. Your endpoint receives each delete_issue call and answers, for example:
{"decision": "block", "user_message": "Deleting issues is not allowed by ACME policy."}
To let a call through, answer {"decision": "allow"}.
The hook resource
Secrets. Secret values are encrypted and never returned: reads show ********. On PATCH, send ******** to keep a value, a new value to rotate it, or null to remove it; leave secrets out to keep them all. Every secret must be used by auth or signing.
PATCH merges the top-level fields you send over the hook. PATCH and DELETE need If-Match with the hook's version in quotes, for example If-Match: "h1" (see versions and If-Match). To change a hook to or from on_complete, send null for the fields the new stage does not take: endpoint and mode, or export. send goes back to the new stage's defaults unless you send it.
What your endpoint receives
A POST with JSON:
{
"version": "1",
"hook": "hook_3f2a9c0b1d4e5f6a7b8c",
"stage": "pre_call",
"request_id": "0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e",
"tenant_id": "tenant-123",
"timestamp": "2026-11-17T10:00:00.000Z",
"mcp": {"id": "a1b2c3d4", "name": "Jira Cloud"},
"tool": {"name": "delete_issue"},
"arguments": {"issue_key": "OPS-42"},
"user": {"email": "dana@example.com"}
}
On post_call it also carries result: the tool's content, isError and structuredContent. request_id is the same for the pre_call and post_call of one tool call. A test call (POST /hooks/{hook_id}/test) carries "test": true and sample values.
What your endpoint returns
Answer 2xx with JSON:
The reply can be at most 64 KB. A non-2xx status, a body that is not JSON, or a missing or unknown decision is a failure.
Several hooks. Hooks on the same stage run in parallel. The strictest enforce decision wins (block over flag over allow). observe hooks never change the call.
What the AI sees on a block. The tool call returns an error result (isError: true) whose text is your user_message. Every call records each hook that ran: hook id, name, stage, mode, decision, latency, the HTTP status, and an error code or your reason and labels.
Timeouts and failures
A call fails on a timeout, a connection error, a non-2xx or unreadable reply, a reply over 64 KB, or a destination the gateway does not call. Then endpoint.on_failure applies: allow lets the call continue, block stops it. On an observe hook the failure is only recorded.
Circuit breaker. After 5 failures in a row on a gateway server, that server skips the hook for 30 seconds and applies its on_failure without a call. Export hooks have no breaker.
Export finished tool calls
An on_complete hook sends one record per finished tool call to export.url, in batches. Records cover tool calls through the MCP's own endpoint and through OneMCP, including calls a hook or DLP blocked and calls that failed. Each call a custom tool's script makes is exported as its own record, with no hooks in it.
curl -X POST https://mcpgateway.quilr.ai/mcpgateway/management/v1/hooks \
-H "Authorization: Bearer $QUILR_MCP_MANAGEMENT_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Tool calls to SIEM",
"stage": "on_complete",
"export": {
"url": "https://siem.example.com/mcp",
"auth": {"type": "bearer", "secret": "token"},
"batch_size": 200,
"flush_ms": 5000
},
"secrets": {"token": "<your token>"}
}'
Your endpoint receives a POST with {"records": [...]}:
{
"records": [
{
"version": "1",
"stage": "on_complete",
"hook": "hook_9b8c7d6e5f4a3b2c1d0e",
"request_id": "0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e",
"tenant_id": "tenant-123",
"timestamp": "2026-11-17T10:00:01.200Z",
"mcp": {"id": "a1b2c3d4", "name": "Jira Cloud"},
"tool": {"name": "delete_issue"},
"outcome": {"status": "blocked", "blocked_by": "pre_call_hook", "failure_stage": null},
"latency_ms": 120,
"hooks": [{"hook_id": "hook_3f2a9c0b1d4e5f6a7b8c", "name": "ACME tool check", "stage": "pre_call",
"mode": "enforce", "decision": "block", "ms": 38, "status_code": 200, "error": null}],
"user": {"email": "dana@example.com"}
}
]
}
outcome.statusissuccess,error(the tool or the MCP failed) orblocked.blocked_byispre_call_hook,post_call_hook,dlp_inputordlp_output.hookslists thepre_callandpost_callhooks that ran on the call.request_idmatches theirs.arguments(the tool arguments as the AI sent them) andresult(what the AI received) are included only withsend.argumentsandsend.result.
- Delivery: any
2xxwithin 30 seconds delivers the batch. Each batch is tried up to 3 times with the sameIdempotency-Key, so deduplicate on it. Batches are signed and authenticated like other hook calls. - While your endpoint is down: after a batch fails all its tries, the hook is unhealthy. The gateway keeps only the latest 100 records for it and sends one probe batch every 30 seconds; when one succeeds, normal delivery resumes.
- Retention: each gateway server queues at most 50,000 records per hook and 256 MB for all hooks together; the oldest are dropped first. Deleting or disabling a hook drops its queued records, and so does changing
export.urlorsend: records captured for the old settings are never sent to the new ones. A single record larger thanexport.max_batch_bytesis dropped. Dropped records are counted indropped. - Health:
GET /hooks/{hook_id}/statsshows the queue on the gateway server that answers. Itsexportobject hashealthy,queued,queued_bytes,delivered,dropped,failed_batches,last_errorandlast_success(exportisnullforpre_callandpost_callhooks);breaker_openshows whether apre_callorpost_callhook is being skipped. The console shows a summary under Export health (this server).
Verify calls
With endpoint.signing, every call carries X-Quilr-Signature: t=<unix seconds>,v1=<hex>, where the hex value is the HMAC-SHA256 of <t>. followed by the raw body, keyed with your signing secret. Recompute it and compare, and reject old timestamps:
import hashlib, hmac, time
def verify(header: str | None, body: bytes, secret: str, max_age: int = 300) -> bool:
parts = dict(item.split("=", 1) for item in (header or "").split(",") if "=" in item)
stamp, signature = parts.get("t", ""), parts.get("v1", "")
if not stamp.isdigit() or not signature:
return False # missing or malformed header
if abs(time.time() - int(stamp)) > max_age:
return False
expected = hmac.new(secret.encode(), f"{stamp}.".encode() + body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature)
Security
- The URL must be a public
httpsaddress. Quilr addresses and private or local IP addresses are refused when you save (400 blocked_destination); a host name that resolves to a private address is refused when the gateway connects. Redirects are not followed. - Secret values are encrypted at rest, sent only in headers, and never returned.
- Turn off
send.arguments,send.resultorsend.userto keep that data off your endpoint.
Test a hook
POST /hooks/{hook_id}/test sends a sample call for the hook's stage to your endpoint (with "test": true, a sample tool, and a sample result on post_call), whether the hook is enabled or not, and returns ok, status_code, ms, error and your reply as the gateway read it. An on_complete test sends one batch with one sample record, once, and reply is null. Use it after creating a hook and after rotating secrets.
Limits
Going over the hook count or the enforce hooks per stage is 422 hook_limit. An out-of-range timeout or more than 8 secrets is 400 invalid_request.
Errors
Endpoints
/hooksList hooks
Every hook of the tenant, enabled or not, with secrets masked, plus the limits.
readNo request body.
curl --request GET \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/hooks' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Scopes Try it in the playground
/hooksCreate a hook
Adds a hook (201). It applies to tool calls within a few seconds. 400 `invalid_request` when the URL is not https, 400 `blocked_destination` when it points to a private or Quilr address, 400 `unknown_secret` when auth or signing names a secret not sent under `secrets`, 422 `hook_limit` over the limits.
hooks:writeFull request body specification application/json
pre_call and post_call need `endpoint`; on_complete needs `export` and takes no `mode` or `endpoint`.
all_mcpsbooleanoptionaltrue: every MCP of the tenant. false: only `scope.mcp_ids`.
descriptionstring | nulloptionalenabledbooleanoptionalendpointobject | nulloptionalpre_call and post_call only.
Variant 1 object
authobjectoptionalHow the gateway signs in to your service. bearer: `Authorization: Bearer <secret>`; basic: username and password secrets; api_key: the secret in `header`.
Object fields
headerstringoptionalapi_key only: the header that carries the key (default `X-API-Key`).
password_secretstringoptionalName of a value under `secrets`.
secretstringoptionalName of a value under `secrets`.
typestringoptional"none""bearer""basic""api_key"username_secretstringoptionalName of a value under `secrets`.
Unknown fields are rejected in this object.
on_failurestringoptionalWhat a failed call means (timeout, an answer other than 2xx, an unreadable reply). Applies to `enforce` hooks.
"allow""block"signingobject | nulloptionalSign every request with the HMAC secret named here.
Variant 1 object
secretstringrequiredName of a value under `secrets`.
Unknown fields are rejected in this object.
Also accepts null.
timeout_msintegeroptionalurlstringrequiredhttps URL on a public address.
Unknown fields are rejected in this object.
Also accepts null.
exportobject | nulloptionalVariant 1 object
authobjectoptionalHow the gateway signs in to your service. bearer: `Authorization: Bearer <secret>`; basic: username and password secrets; api_key: the secret in `header`.
Object fields
headerstringoptionalapi_key only: the header that carries the key (default `X-API-Key`).
password_secretstringoptionalName of a value under `secrets`.
secretstringoptionalName of a value under `secrets`.
typestringoptional"none""bearer""basic""api_key"username_secretstringoptionalName of a value under `secrets`.
Unknown fields are rejected in this object.
batch_sizeintegeroptionalflush_msintegeroptionalmax_batch_bytesintegeroptionalsigningobject | nulloptionalSign every batch with the HMAC secret named here.
Variant 1 object
secretstringrequiredName of a value under `secrets`.
Unknown fields are rejected in this object.
Also accepts null.
urlstringrequiredhttps URL on a public address.
Unknown fields are rejected in this object.
Also accepts null.
modestring | nulloptionalpre_call and post_call only. observe: called and logged, never changes the call.
"enforce""observe"nullnamestringrequiredscopeobjectoptionalObject fields
mcp_idsarray<string>optionalMCPs the hook applies to when `all_mcps` is false.
Array item specification
stringtoolsarray<string>optionalOnly these tool names; empty means every tool.
Array item specification
stringUnknown fields are rejected in this object.
secretsmap<string, string | null>optionalWrite only, by name (`[a-z][a-z0-9_]*`). Reads show `********`. On a change, sending `********` keeps the saved value, `null` removes it; leaving `secrets` out keeps all of them. Every secret must be used by the auth or signing of `endpoint` (or `export`).
Map value specification
string | nullsendobjectoptionalWhich parts of the call your service receives.
Object fields
argumentsbooleanoptionalDefault true, false for on_complete.
resultbooleanoptionalDefault true for post_call, false for on_complete. Never sent on pre_call.
userbooleanoptionalUnknown fields are rejected in this object.
stagestringrequiredpre_call and post_call need `endpoint`; on_complete needs `export`.
"pre_call""post_call""on_complete"Unknown fields are rejected in this object.
curl --request POST \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/hooks' \
--header 'Authorization: Bearer <management-key>' \
--header 'Content-Type: application/json' \
--data '{
"all_mcps": false,
"description": "Checks file tools before they run.",
"endpoint": {
"auth": {
"secret": "token",
"type": "bearer"
},
"on_failure": "allow",
"signing": {
"secret": "signing_key"
},
"timeout_ms": 1500,
"url": "https://hooks.example.com/mcp/pre-call"
},
"mode": "enforce",
"name": "Block exports to personal drives",
"scope": {
"mcp_ids": [
"a1b2c3d4"
],
"tools": [
"upload_file"
]
},
"secrets": {
"signing_key": "example-signing-value",
"token": "example-token-value"
},
"stage": "pre_call"
}'
Authentication, errors & retry rules Scopes Try it in the playground
/hooks/{hook_id}Delete a hook
Removes the hook and its secrets. Send the quoted `version` from the latest read in If-Match (428 when missing, 412 when stale).
hooks:writePath, query & header parameters 2
hook_id (path)stringrequiredHook id, from the create response or the list.
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/hooks/hook_3f9a1c2b7d4e5f60a1b2' \
--header 'Authorization: Bearer <management-key>' \
--header 'If-Match: "h1"'
Authentication, errors & retry rules Scopes Try it in the playground
/hooks/{hook_id}Read a hook
One hook, secrets masked. `version` is the If-Match value for changes.
readPath, query & header parameters 1
hook_id (path)stringrequiredHook id, from the create response or the list.
No request body.
curl --request GET \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/hooks/hook_3f9a1c2b7d4e5f60a1b2' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Scopes Try it in the playground
/hooks/{hook_id}Change a hook
Changes the sent fields and keeps the rest, for example `{"enabled": false}` to pause it or `{"mode": "observe"}` to try it without blocking. Send the quoted `version` from the latest read in If-Match (428 when missing, 412 when stale).
hooks:writePath, query & header parameters 2
hook_id (path)stringrequiredHook id, from the create response or the list.
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. `endpoint`, `export`, `scope` and `send` are replaced as a whole. To move a hook to or from on_complete, send `null` for the fields the new stage does not take (`endpoint` and `mode`, or `export`).
all_mcpsbooleanoptionaltrue: every MCP of the tenant. false: only `scope.mcp_ids`.
descriptionstring | nulloptionalenabledbooleanoptionalendpointobject | nulloptionalpre_call and post_call only.
Variant 1 object
authobjectoptionalHow the gateway signs in to your service. bearer: `Authorization: Bearer <secret>`; basic: username and password secrets; api_key: the secret in `header`.
Object fields
headerstringoptionalapi_key only: the header that carries the key (default `X-API-Key`).
password_secretstringoptionalName of a value under `secrets`.
secretstringoptionalName of a value under `secrets`.
typestringoptional"none""bearer""basic""api_key"username_secretstringoptionalName of a value under `secrets`.
Unknown fields are rejected in this object.
on_failurestringoptionalWhat a failed call means (timeout, an answer other than 2xx, an unreadable reply). Applies to `enforce` hooks.
"allow""block"signingobject | nulloptionalSign every request with the HMAC secret named here.
Variant 1 object
secretstringrequiredName of a value under `secrets`.
Unknown fields are rejected in this object.
Also accepts null.
timeout_msintegeroptionalurlstringrequiredhttps URL on a public address.
Unknown fields are rejected in this object.
Also accepts null.
exportobject | nulloptionalVariant 1 object
authobjectoptionalHow the gateway signs in to your service. bearer: `Authorization: Bearer <secret>`; basic: username and password secrets; api_key: the secret in `header`.
Object fields
headerstringoptionalapi_key only: the header that carries the key (default `X-API-Key`).
password_secretstringoptionalName of a value under `secrets`.
secretstringoptionalName of a value under `secrets`.
typestringoptional"none""bearer""basic""api_key"username_secretstringoptionalName of a value under `secrets`.
Unknown fields are rejected in this object.
batch_sizeintegeroptionalflush_msintegeroptionalmax_batch_bytesintegeroptionalsigningobject | nulloptionalSign every batch with the HMAC secret named here.
Variant 1 object
secretstringrequiredName of a value under `secrets`.
Unknown fields are rejected in this object.
Also accepts null.
urlstringrequiredhttps URL on a public address.
Unknown fields are rejected in this object.
Also accepts null.
modestring | nulloptionalpre_call and post_call only. observe: called and logged, never changes the call.
"enforce""observe"nullnamestringoptionalscopeobjectoptionalObject fields
mcp_idsarray<string>optionalMCPs the hook applies to when `all_mcps` is false.
Array item specification
stringtoolsarray<string>optionalOnly these tool names; empty means every tool.
Array item specification
stringUnknown fields are rejected in this object.
secretsmap<string, string | null>optionalWrite only, by name (`[a-z][a-z0-9_]*`). Reads show `********`. On a change, sending `********` keeps the saved value, `null` removes it; leaving `secrets` out keeps all of them. Every secret must be used by the auth or signing of `endpoint` (or `export`).
Map value specification
string | nullsendobjectoptionalWhich parts of the call your service receives.
Object fields
argumentsbooleanoptionalDefault true, false for on_complete.
resultbooleanoptionalDefault true for post_call, false for on_complete. Never sent on pre_call.
userbooleanoptionalUnknown fields are rejected in this object.
stagestringoptionalpre_call and post_call need `endpoint`; on_complete needs `export`.
"pre_call""post_call""on_complete"Unknown fields are rejected in this object.
curl --request PATCH \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/hooks/hook_3f9a1c2b7d4e5f60a1b2' \
--header 'Authorization: Bearer <management-key>' \
--header 'If-Match: "h1"' \
--header 'Content-Type: application/json' \
--data '{
"mode": "observe"
}'
Authentication, errors & retry rules Scopes Try it in the playground
/hooks/{hook_id}/statsRead a hook's delivery state
For an on_complete hook, the answering gateway server's export state: queued, delivered, dropped and failed batches, the last error and the last delivery. `export` is null for pre_call and post_call hooks.
readPath, query & header parameters 1
hook_id (path)stringrequiredHook id, from the create response or the list.
No request body.
curl --request GET \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/hooks/hook_3f9a1c2b7d4e5f60a1b2/stats' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Scopes Try it in the playground
/hooks/{hook_id}/testSend a test call to a hook
Sends a sample request for the hook's stage (with `"test": true` and example values, never real data) to its endpoint, with its auth and signing, and returns what happened. An on_complete hook gets one sample batch `{"records": [...]}`, sent once and outside its queue. Works for disabled hooks. Nothing is blocked or logged as a tool call.
hooks:writePath, query & header parameters 1
hook_id (path)stringrequiredHook id, from the create response or the list.
Full request body specification application/json
No body, or an empty JSON object.
Unknown fields are rejected in this object.
curl --request POST \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/hooks/hook_3f9a1c2b7d4e5f60a1b2/test' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Scopes Try it in the playground