Tool changes and tenant API
Try these operations with your own key in the MCP Management API playground.
Tool changes
The tool watch compares each MCP's upstream tool list with the cached one. GET /tool-changes returns one row per MCP (pending_only=true for those with a change awaiting review), and GET /mcps/{mcp_id}/tool-changes one MCP with the tools added, removed and modified upstream. What happens on a change depends on the MCP's tool_sync setting (notify, auto or off).
These need tool_reviews:write. A failed check reports a fixed reason_code (for example auth_failed or unreachable), never upstream text. A failed check, or one where upstream lists no tools while the cache has some, never discards a pending change: its status and version stay, and only the check time and reason change.
Apply or dismiss the change you reviewed
Every tool-change view (in GET /tool-changes, GET /mcps/{mcp_id}/tool-changes and the apply, dismiss and check responses) carries version: c followed by 24 hexadecimal characters, derived from exactly the difference shown, or null when nothing is pending. The single read also returns it as the ETag header. Apply and dismiss require it in If-Match, so they act only on the change you reviewed:
curl --request POST "$GW/mcpgateway/management/v1/mcps/a1b2c3d4/tool-changes/apply" \
--header "Authorization: Bearer $KEY" \
--header 'If-Match: "c3f1a9e07b52d4c68e1f0a2b"'
The same sweep finding the same difference keeps the version, so a version you read stays valid until the difference itself changes.
GET /mcps/{mcp_id}/oauth-scope-options lists the permission bundles the provider offers for an OAuth MCP and the stored selection. Select bundles with oauth_scopes in the MCP's settings.
Tenant settings
GET /tenant/settings returns the organization switches, each with who changed it last:
PATCH /tenant/settings changes any of the sections. It needs tenant_settings:write and If-Match with the version from the read. The response also shows the data-retention policy revision, which is managed in the console, and whether QuilrQL policies govern the organization (policy_authority.mode); under QuilrQL the switches are stored but the policies decide.
Tool-argument aliases
An alias rewrites the arguments clients send before a call reaches the MCP. Every spec has version: 1, kind, tool_name, and optionally action (for tools that dispatch on an action argument) and path (nested objects; [] is the top level):
{"version": 1, "kind": "param_alias", "tool_name": "get_work_item", "action": null, "path": [], "from": "id", "to": "work_item_id"}
POST /tool-arg-aliases with {"mcp_id", "spec"} adds one after checking it against the tool's input schema (400 when it does not fit). PUT /tool-arg-aliases/{alias_id} creates or replaces an alias under an id you choose, spec included. GET /tool-arg-aliases lists them (filter with mcp_id and tool_name); active is false when an alias is disabled or no longer fits the tool's current schema. PATCH changes enabled and note; DELETE removes one. Writes need tenant_settings:write.
MCP requests
Users can ask for an MCP Library entry from their dashboard. GET /mcp-requests lists pending requests, newest first, with what installing each entry needs. Installing the entry (POST /catalog/{catalog_id}/install) fulfils every pending request for it. POST /mcp-requests/{request_id}/dismiss dismisses one request (tenant_settings:write).
Endpoint reference
/mcps/{mcp_id}/oauth-scope-optionsRead OAuth permission options
Permission bundles the provider offers for this OAuth MCP and the stored selection. Select bundles with settings `oauth_scopes` (PATCH /mcps/{mcp_id}/settings).
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/oauth-scope-options' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Scopes Try it in the playground
/mcps/{mcp_id}/tool-changesRead tool-change state
Status, the tools added, removed or modified upstream, and when it was last checked. A pending change carries `version` (also the ETag): the If-Match value for apply and dismiss.
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/tool-changes' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Scopes Try it in the playground
/mcps/{mcp_id}/tool-changes/applyAdopt the reviewed upstream tool list
Adopts the change you reviewed: send its `version` quoted in If-Match (428 when missing). The upstream tool list is fetched again and adopted only when it still matches the reviewed change; otherwise nothing is adopted and the answer is 412 `tool_changes_changed` with the current change in `error.tool_changes` (review it and retry with its `version`). A change that was replaced or closed since the read (by a check, another apply or a dismiss) is 412 `version_conflict`, also with `error.tool_changes` (its `version` is null when nothing is pending any more). New tools may still be held for review. 409 `tool_changes_unavailable` when the upstream tool list cannot be read now (nothing adopted).
tool_reviews:writePath, query & header parameters 2
mcp_id (path)stringrequiredMCP id (the `id` of an MCP, not its slug).
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 POST \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/mcps/a1b2c3d4/tool-changes/apply' \
--header 'Authorization: Bearer <management-key>' \
--header 'If-Match: "c3f1a9e07b52d4c68e1f0a2b"'
Authentication, errors & retry rules Scopes Try it in the playground
/mcps/{mcp_id}/tool-changes/checkCheck for tool changes now
Compares the upstream tool list with the cached one now.
tool_reviews:writePath, query & header parameters 1
mcp_id (path)stringrequiredMCP id (the `id` of an MCP, not its slug).
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/mcps/a1b2c3d4/tool-changes/check' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Scopes Try it in the playground
/mcps/{mcp_id}/tool-changes/dismissDismiss a tool change
Keeps the cached tool list and stops flagging this upstream list; a different upstream list opens a new change. Send the reviewed change's `version` quoted in If-Match (428 when missing); a change that was replaced, applied or dismissed since the read is 412 `version_conflict` with the current state in `error.tool_changes` (`version` null when nothing is pending).
tool_reviews:writePath, query & header parameters 2
mcp_id (path)stringrequiredMCP id (the `id` of an MCP, not its slug).
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 POST \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/mcps/a1b2c3d4/tool-changes/dismiss' \
--header 'Authorization: Bearer <management-key>' \
--header 'If-Match: "c3f1a9e07b52d4c68e1f0a2b"'
Authentication, errors & retry rules Scopes Try it in the playground
/tool-changesList tool-change state
One row per MCP: whether the upstream tool list differs from the cached one. Pending rows carry the change's `version` for apply and dismiss.
readPath, query & header parameters 3
limit (query)integeroptionalPage size, 1 to 200 (default 50).
cursor (query)stringoptionalThe `next_cursor` of the previous page. 409 `collection_changed` when the list changed; restart.
pending_only (query)booleanoptionaltrue lists only MCPs with a change awaiting review.
No request body.
curl --request GET \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/tool-changes?limit=50' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Scopes Try it in the playground
/mcp-requestsList users' MCP requests
Pending requests from users for MCP Library entries, newest first, with what installing each entry needs. Installing the entry (POST /catalog/{catalog_id}/install) resolves every pending request for it.
readPath, query & header parameters 2
limit (query)integeroptionalPage size, 1 to 200 (default 50).
cursor (query)stringoptionalThe `next_cursor` of the previous page. 409 `collection_changed` when the list changed; restart.
No request body.
curl --request GET \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/mcp-requests?limit=50' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Scopes Try it in the playground
/mcp-requests/{request_id}/dismissDismiss an MCP request
Dismisses one pending request. Dismissing twice is a no-op; a request already resolved by an install answers 409 `request_not_pending`.
tenant_settings:writePath, query & header parameters 1
request_id (path)stringrequiredRequest id (`request_id` from `GET /mcp-requests`).
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/mcp-requests/9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d/dismiss' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Scopes Try it in the playground
/tenant/settingsRead tenant settings
Tenant switches and the data-retention status (managed in the Quilr console). When QuilrQL policies govern the tenant, the switches are stored but the policies decide.
readNo request body.
curl --request GET \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/tenant/settings' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Scopes Try it in the playground
/tenant/settingsUpdate tenant settings
Changes any of smart_mode, memories and tool_review. Send the quoted `version` from the latest read in If-Match (428 when missing, 412 when stale).
tenant_settings:writePath, query & header parameters 1
If-Match (header)stringrequiredQuoted `version` (ETag) from the latest read of this resource.
Full request body specification application/json
Send at least one section.
memoriesobjectoptionalMemories for users and OneMCP.
Object fields
enabledbooleanrequiredUnknown fields are rejected in this object.
smart_modeobjectoptionalDynamic Tool Calling for OneMCP: follow each user's preference, or force it on or off.
Object fields
modestringrequired"user_preference""force_enabled""force_disabled"Unknown fields are rejected in this object.
tool_reviewobjectoptionalHold new upstream tools for review on every MCP that inherits the tenant default.
Object fields
hold_new_toolsbooleanrequiredUnknown fields are rejected in this object.
Unknown fields are rejected in this object.
curl --request PATCH \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/tenant/settings' \
--header 'Authorization: Bearer <management-key>' \
--header 'If-Match: "t5e0c2b9a7d413f86"' \
--header 'Content-Type: application/json' \
--data '{
"memories": {
"enabled": false
}
}'
Authentication, errors & retry rules Scopes Try it in the playground
/tool-arg-aliasesList tool-argument aliases
Aliases that rewrite the arguments clients send (parameter renames and value normalizations) before a call reaches the MCP.
readPath, query & header parameters 4
limit (query)integeroptionalPage size, 1 to 200 (default 50).
cursor (query)stringoptionalThe `next_cursor` of the previous page. 409 `collection_changed` when the list changed; restart.
mcp_id (query)stringoptionalOnly aliases of this MCP.
tool_name (query)stringoptionalOnly aliases of this tool.
No request body.
curl --request GET \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/tool-arg-aliases?limit=50' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Scopes Try it in the playground
/tool-arg-aliasesCreate a tool-argument alias
Adds an alias after checking it against the tool's input schema (400 when it does not fit).
tenant_settings:writeFull request body specification application/json
enabledbooleanoptionalmcp_idstringrequiredMCP whose tool the alias applies to.
notestring | nulloptionalspecone of 3 variantsrequiredAlias specification for one tool, checked against its input schema.
Parameter alias object
actionstring | nulloptionalAction name for tools that dispatch on an action argument; null otherwise.
fromstringrequiredName clients send.
kind"param_alias"requiredpatharray<string>optionalPath of nested objects the rule applies inside; [] is the top level.
Array item specification
stringtostringrequiredName the tool expects.
tool_namestringrequiredversionintegerrequired1Value normalization object
actionstring | nulloptionalAction name for tools that dispatch on an action argument; null otherwise.
from_valuesarray<string>requiredArray item specification
stringkind"value_normalization"requiredmatchstringrequirednormalized ignores case, spaces and punctuation.
"exact""normalized"paramstringrequiredpatharray<string>optionalPath of nested objects the rule applies inside; [] is the top level.
Array item specification
stringto_valuestringrequiredtool_namestringrequiredversionintegerrequired1Envelope wrap or unwrap object
actionstring | nulloptionalAction name for tools that dispatch on an action argument; null otherwise.
kindstringrequired"envelope_wrap""envelope_unwrap"patharray<string>optionalPath of nested objects the rule applies inside; [] is the top level.
Array item specification
stringtool_namestringrequiredversionintegerrequired1Unknown fields are rejected in this object.
curl --request POST \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/tool-arg-aliases' \
--header 'Authorization: Bearer <management-key>' \
--header 'Content-Type: application/json' \
--data '{
"mcp_id": "a1b2c3d4",
"spec": {
"action": null,
"from": "id",
"kind": "param_alias",
"path": [],
"to": "work_item_id",
"tool_name": "get_work_item",
"version": 1
}
}'
Authentication, errors & retry rules Scopes Try it in the playground
/tool-arg-aliases/{alias_id}Delete a tool-argument alias
Deletes the alias.
tenant_settings:writePath, query & header parameters 1
alias_id (path)stringrequiredAlias id (`alias_id`).
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/tool-arg-aliases/7d2e4f60-1a2b-4c3d-9e8f-0a1b2c3d4e5f' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Scopes Try it in the playground
/tool-arg-aliases/{alias_id}Read a tool-argument alias
One alias.
readPath, query & header parameters 1
alias_id (path)stringrequiredAlias id (`alias_id`).
No request body.
curl --request GET \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/tool-arg-aliases/7d2e4f60-1a2b-4c3d-9e8f-0a1b2c3d4e5f' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Scopes Try it in the playground
/tool-arg-aliases/{alias_id}Enable, disable or annotate an alias
Changes `enabled` and/or `note`.
tenant_settings:writePath, query & header parameters 1
alias_id (path)stringrequiredAlias id (`alias_id`).
Full request body specification application/json
Send at least one field.
enabledbooleanoptionalnotestring | nulloptionalUnknown fields are rejected in this object.
curl --request PATCH \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/tool-arg-aliases/7d2e4f60-1a2b-4c3d-9e8f-0a1b2c3d4e5f' \
--header 'Authorization: Bearer <management-key>' \
--header 'Content-Type: application/json' \
--data '{
"enabled": false
}'
Authentication, errors & retry rules Scopes Try it in the playground
/tool-arg-aliases/{alias_id}Create or replace a tool-argument alias
Creates the alias with this id (for example an accepted suggestion's id) or replaces it, spec included. 409 `alias_id_in_use` when the id belongs to another organization.
tenant_settings:writePath, query & header parameters 1
alias_id (path)stringrequiredAlias id (`alias_id`).
Full request body specification application/json
Creates the alias with this id, or replaces it (spec included).
enabledbooleanoptionalmcp_idstringrequiredMCP whose tool the alias applies to.
notestring | nulloptionalspecone of 3 variantsrequiredAlias specification for one tool, checked against its input schema.
Parameter alias object
actionstring | nulloptionalAction name for tools that dispatch on an action argument; null otherwise.
fromstringrequiredName clients send.
kind"param_alias"requiredpatharray<string>optionalPath of nested objects the rule applies inside; [] is the top level.
Array item specification
stringtostringrequiredName the tool expects.
tool_namestringrequiredversionintegerrequired1Value normalization object
actionstring | nulloptionalAction name for tools that dispatch on an action argument; null otherwise.
from_valuesarray<string>requiredArray item specification
stringkind"value_normalization"requiredmatchstringrequirednormalized ignores case, spaces and punctuation.
"exact""normalized"paramstringrequiredpatharray<string>optionalPath of nested objects the rule applies inside; [] is the top level.
Array item specification
stringto_valuestringrequiredtool_namestringrequiredversionintegerrequired1Envelope wrap or unwrap object
actionstring | nulloptionalAction name for tools that dispatch on an action argument; null otherwise.
kindstringrequired"envelope_wrap""envelope_unwrap"patharray<string>optionalPath of nested objects the rule applies inside; [] is the top level.
Array item specification
stringtool_namestringrequiredversionintegerrequired1Unknown fields are rejected in this object.
curl --request PUT \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/tool-arg-aliases/7d2e4f60-1a2b-4c3d-9e8f-0a1b2c3d4e5f' \
--header 'Authorization: Bearer <management-key>' \
--header 'Content-Type: application/json' \
--data '{
"mcp_id": "a1b2c3d4",
"spec": {
"action": null,
"from": "id",
"kind": "param_alias",
"path": [],
"to": "work_item_id",
"tool_name": "get_work_item",
"version": 1
}
}'
Authentication, errors & retry rules Scopes Try it in the playground