Skip to main content

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

OperationEffect
POST /mcps/{mcp_id}/tool-changes/checkCompare with the upstream list now.
POST /mcps/{mcp_id}/tool-changes/applyReplace the cached tool list with the upstream one, if upstream still serves the change you reviewed. New tools may still be held for review.
POST /mcps/{mcp_id}/tool-changes/dismissKeep the cached list and stop flagging this upstream list. A different upstream list opens a new change.

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"'
ResponseMeaning
428 precondition_requiredIf-Match is missing.
412 version_conflictThe pending change is no longer the one you reviewed: upstream moved again and a check recorded a new difference, or the change was applied or dismissed since your read, also while your apply was running (for example by another gateway process). Nothing is adopted. error.tool_changes holds the current state; its version is null when nothing is pending any more.
412 tool_changes_changedApply only: the gateway fetched the upstream list again and it no longer matches the reviewed change, or the cached tool list changed during the apply (for example a tool refresh). Nothing was adopted; the new difference is recorded and returned in error.tool_changes (a clean state when upstream went back to the cached list). Review it and apply again with its version.
409 tool_changes_unavailableApply only: the gateway cannot read the upstream tool list now, for example because upstream lists no tools while the cache has some. Nothing is adopted; retry later.
502 upstream_unavailableApply only: the upstream MCP server could not be reached or rejected the request.

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:

SectionFieldMeaning
smart_modemodeDynamic Tool Calling for OneMCP: user_preference (each user chooses), force_enabled or force_disabled.
memoriesenabledMemories for users and OneMCP.
tool_reviewhold_new_toolsHold new upstream tools for review on every MCP that inherits the organization default.

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):

kindRequired fields
param_aliasfrom (name clients send), to (name the tool expects)
value_normalizationparam, match (exact or normalized, which ignores case, spaces and punctuation), from_values, to_value
envelope_wrap, envelope_unwrapnone (top level only)
{"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​

GET/mcps/{mcp_id}/oauth-scope-options

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

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/oauth-scope-options' \
--header 'Authorization: Bearer <management-key>'

Authentication, errors & retry rules Scopes Try it in the playground

GET/mcps/{mcp_id}/tool-changes

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

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/tool-changes' \
--header 'Authorization: Bearer <management-key>'

Authentication, errors & retry rules Scopes Try it in the playground

POST/mcps/{mcp_id}/tool-changes/apply

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

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

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

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

POST/mcps/{mcp_id}/tool-changes/check

Check for tool changes now

Compares the upstream tool list with the cached one now.

REQUIREStool_reviews:write
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

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

POST/mcps/{mcp_id}/tool-changes/dismiss

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

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

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

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

GET/tool-changes

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

REQUIRESread
Path, query & header parameters 3
limit (query)integeroptional

Page size, 1 to 200 (default 50).

min: 1max: 200default: 50
cursor (query)stringoptional

The `next_cursor` of the previous page. 409 `collection_changed` when the list changed; restart.

pending_only (query)booleanoptional

true 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

GET/mcp-requests

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

REQUIRESread
Path, query & header parameters 2
limit (query)integeroptional

Page size, 1 to 200 (default 50).

min: 1max: 200default: 50
cursor (query)stringoptional

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

POST/mcp-requests/{request_id}/dismiss

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

REQUIREStenant_settings:write
Path, query & header parameters 1
request_id (path)stringrequired

Request 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

GET/tenant/settings

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

REQUIRESread

No 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

PATCH/tenant/settings

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

REQUIREStenant_settings:write
Path, query & header parameters 1
If-Match (header)stringrequired

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

Full request body specification application/json

Send at least one section.

memoriesobjectoptional

Memories for users and OneMCP.

Object fields
enabledbooleanrequired

Unknown fields are rejected in this object.

smart_modeobjectoptional

Dynamic 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_reviewobjectoptional

Hold new upstream tools for review on every MCP that inherits the tenant default.

Object fields
hold_new_toolsbooleanrequired

Unknown 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

GET/tool-arg-aliases

List tool-argument aliases

Aliases that rewrite the arguments clients send (parameter renames and value normalizations) before a call reaches the MCP.

REQUIRESread
Path, query & header parameters 4
limit (query)integeroptional

Page size, 1 to 200 (default 50).

min: 1max: 200default: 50
cursor (query)stringoptional

The `next_cursor` of the previous page. 409 `collection_changed` when the list changed; restart.

mcp_id (query)stringoptional

Only aliases of this MCP.

tool_name (query)stringoptional

Only 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

POST/tool-arg-aliases

Create a tool-argument alias

Adds an alias after checking it against the tool's input schema (400 when it does not fit).

REQUIREStenant_settings:write
Full request body specification application/json

enabledbooleanoptional
default: true
mcp_idstringrequired

MCP whose tool the alias applies to.

notestring | nulloptional
max length: 2000
specone of 3 variantsrequired

Alias specification for one tool, checked against its input schema.

Parameter alias object
actionstring | nulloptional

Action name for tools that dispatch on an action argument; null otherwise.

fromstringrequired

Name clients send.

min length: 1
kind"param_alias"required
patharray<string>optional

Path of nested objects the rule applies inside; [] is the top level.

default: []
Array item specification
string
min length: 1
tostringrequired

Name the tool expects.

min length: 1
tool_namestringrequired
min length: 1
versionintegerrequired
1
Value normalization object
actionstring | nulloptional

Action name for tools that dispatch on an action argument; null otherwise.

from_valuesarray<string>required
min items: 1
Array item specification
string
kind"value_normalization"required
matchstringrequired

normalized ignores case, spaces and punctuation.

"exact""normalized"
paramstringrequired
min length: 1
patharray<string>optional

Path of nested objects the rule applies inside; [] is the top level.

default: []
Array item specification
string
min length: 1
to_valuestringrequired
min length: 1
tool_namestringrequired
min length: 1
versionintegerrequired
1
Envelope wrap or unwrap object
actionstring | nulloptional

Action name for tools that dispatch on an action argument; null otherwise.

kindstringrequired
"envelope_wrap""envelope_unwrap"
patharray<string>optional

Path of nested objects the rule applies inside; [] is the top level.

default: []
Array item specification
string
min length: 1
tool_namestringrequired
min length: 1
versionintegerrequired
1

Unknown 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

DELETE/tool-arg-aliases/{alias_id}

Delete a tool-argument alias

Deletes the alias.

REQUIREStenant_settings:write
Path, query & header parameters 1
alias_id (path)stringrequired

Alias 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

PATCH/tool-arg-aliases/{alias_id}

Enable, disable or annotate an alias

Changes `enabled` and/or `note`.

REQUIREStenant_settings:write
Path, query & header parameters 1
alias_id (path)stringrequired

Alias id (`alias_id`).

Full request body specification application/json

Send at least one field.

enabledbooleanoptional
notestring | nulloptional
max length: 2000

Unknown 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

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

REQUIREStenant_settings:write
Path, query & header parameters 1
alias_id (path)stringrequired

Alias id (`alias_id`).

Full request body specification application/json

Creates the alias with this id, or replaces it (spec included).

enabledbooleanoptional
default: true
mcp_idstringrequired

MCP whose tool the alias applies to.

notestring | nulloptional
max length: 2000
specone of 3 variantsrequired

Alias specification for one tool, checked against its input schema.

Parameter alias object
actionstring | nulloptional

Action name for tools that dispatch on an action argument; null otherwise.

fromstringrequired

Name clients send.

min length: 1
kind"param_alias"required
patharray<string>optional

Path of nested objects the rule applies inside; [] is the top level.

default: []
Array item specification
string
min length: 1
tostringrequired

Name the tool expects.

min length: 1
tool_namestringrequired
min length: 1
versionintegerrequired
1
Value normalization object
actionstring | nulloptional

Action name for tools that dispatch on an action argument; null otherwise.

from_valuesarray<string>required
min items: 1
Array item specification
string
kind"value_normalization"required
matchstringrequired

normalized ignores case, spaces and punctuation.

"exact""normalized"
paramstringrequired
min length: 1
patharray<string>optional

Path of nested objects the rule applies inside; [] is the top level.

default: []
Array item specification
string
min length: 1
to_valuestringrequired
min length: 1
tool_namestringrequired
min length: 1
versionintegerrequired
1
Envelope wrap or unwrap object
actionstring | nulloptional

Action name for tools that dispatch on an action argument; null otherwise.

kindstringrequired
"envelope_wrap""envelope_unwrap"
patharray<string>optional

Path of nested objects the rule applies inside; [] is the top level.

default: []
Array item specification
string
min length: 1
tool_namestringrequired
min length: 1
versionintegerrequired
1

Unknown 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