MCP Gateway Management API
Manage your MCPs.
From scripts, pipelines and code.
List, add, install and remove MCPs, change their settings and upstream credentials, review new tools and upstream tool changes, connect OAuth MCPs, change REST API MCPs, add custom tools, hand MCPs out to clients and people, rotate OAuth clients, see and revoke user connections, change organization switches, and read usage, latency, DLP activity and the audit trail, from one tenant-scoped API.
Use a management key to manage your organization's MCPs from scripts, CI pipelines, infrastructure-as-code and internal tools. Each key belongs to one tenant, carries explicit scopes, and works only while management is enabled for the organization.
With the Management API you can list and inspect MCPs, add, install and remove them, change their settings and upstream credentials, review new tools, connect OAuth MCPs, add custom tools, and read usage analytics and the audit trail. Explore complete input specifications and examples on the pages below, download the OpenAPI 3.1 reference, or send live calls from the MCP Management API playground. Every endpoint below has a Try it in the playground link.
Enable in the console
- Go to Settings > AI Gateway > MCP Gateway and open the Management API tab (next to Servers).
- Turn on Allow management keys for this organization. Turning it off later suspends every management key immediately; keys are kept and work again when you turn it back on.
- Under Issue a management key, enter a Key name, an optional Expiry (leave blank for no expiry), and the scopes the key needs.
- Click Issue key. The Management key created dialog shows the key once: click Copy key, store it in your secret manager, then click Done. It cannot be retrieved later; issue a new key if it is lost.
The Management keys table lists each key's Name, Scopes, Status, Fingerprint, Created, Expires, Last used and Actions. Use the edit action to change a key's Key name, scopes or Expiry (or select Never expires), then click Save changes. Use the revoke action and confirm with Revoke key: automation using the key stops working, and revocation cannot be undone.
Settings > Organization > API keys shows an MCP Gateway management keys card with whether the Management API is on, the number of Active keys and Revoked or expired keys, and a Manage management keys link to this tab.
A key acts for the whole organization within its scopes, and its writes are made as the administrator who issued it. See Authentication and management keys and Scopes for details.
Choose a resource
List, inspect, add, rename, enable, disable and remove MCPs, and list their tools.
Explore referenceMCP LibraryBrowse the catalog and install prebuilt MCPs.
Explore referenceREST API MCPsChange base URL, limits, access rules and which OpenAPI operations become tools; resync the document.
Explore referenceCustom toolsAdd your own tools to an MCP: short Python scripts that chain its tools; validate, test-run and restore earlier versions.
Explore referenceSettings and overridesTools, DLP, token saving, access control, tool exposure and OneMCP settings, per MCP, user or smart group.
Explore referenceUpstream credentialsSet, rotate and remove the credentials the gateway sends upstream.
Explore referenceTool reviewsApprove or reject new tools held for review.
Explore referenceConnections and OAuthConnection state, tool refresh and single-use OAuth connect links.
Explore referenceClient accessEndpoint URLs and client configuration, MCP API tokens and which agents may use each MCP.
Explore referenceUser connectionsWho is connected to each MCP, and making one user connect again.
Explore referenceSign-in links and OAuth clientsA link people open to connect an MCP themselves; rotate OAuth client secrets.
Explore referenceTool changesAdopt or dismiss upstream tool-list changes; OAuth permission options.
Explore referenceOrganization settingsDynamic Tool Calling, Memories, new-tool review, tool-argument aliases and MCP requests.
Explore referenceAnalyticsUsage, latency, DLP activity, tool-call metadata and per-user activity.
Explore referenceAuditConfiguration changes made in the console and through the API.
Explore referenceAuthenticationEnable management and issue scoped management keys.
Explore referenceThe management model
Defaults
- Management keys have no expiry by default. You can set one when you issue the key.
- A key's writes act as the administrator who issued it. If that administrator leaves the organization, the key's writes fail with
409 key_owner_unavailable, as do reads made on that administrator's behalf (custom tools, MCP API tokens, the OAuth client, tool changes, OAuth scope options and aliases); issue a new key. - Credentials set through the API are shared by all users of the organization.
- Setting changes apply immediately to the MCP's own endpoint and to OneMCP.
- A create that carries
settingsor"enabled": falseadds the MCP disabled, applies the settings, and sets the requested state last, so an interrupted create never leaves the MCP usable without its settings.
Find an endpoint
Search by resource, path, action or HTTP method. Open an endpoint to see its scopes, parameters, complete body schema and examples.
93 of 93 operations
/admin/tenants/{tenant_id}/keysList management keys/admin/tenants/{tenant_id}/keysIssue a management key/admin/tenants/{tenant_id}/keys/{key_id}Revoke a management key/admin/tenants/{tenant_id}/keys/{key_id}Read a management key/admin/tenants/{tenant_id}/keys/{key_id}Update a management key/admin/tenants/{tenant_id}/settingsRead tenant management settings/admin/tenants/{tenant_id}/settingsEnable or suspend management/agentsList agents/agentsCreate a custom agent/agents/{keyword}Delete a custom agent/agents/{keyword}Read an agent/api-access/presetsList access rule presets/api-access/testTest candidate access rules/auditList audit events/capabilitiesRead capabilities/catalogList the MCP Library/catalog/{catalog_id}Read a catalog entry/catalog/{catalog_id}/installInstall a catalog MCP/dlp/summaryDLP summary/latencyLatency report/mcp-requestsList users' MCP requests/mcp-requests/{request_id}/dismissDismiss an MCP request/mcpsList MCPs/mcpsAdd a remote MCP/mcps/apiAdd a REST API as an MCP/mcps/api:previewPreview a REST API spec/mcps/{mcp_id}Remove an MCP/mcps/{mcp_id}Read an MCP/mcps/{mcp_id}Rename, describe, enable or disable an MCP/mcps/{mcp_id}/agentsRead which agents may use an MCP/mcps/{mcp_id}/agents/{agent}Allow or block an agent on an MCP/mcps/{mcp_id}/api-configRead a REST API MCP's configuration/mcps/{mcp_id}/api-configChange a REST API MCP's configuration/mcps/{mcp_id}/api-config/access-testTest the saved access rules/mcps/{mcp_id}/api-config/resyncResync the OpenAPI document/mcps/{mcp_id}/api-config/selection-previewPreview which operations would become tools/mcps/{mcp_id}/capabilities:refreshRefresh tools/mcps/{mcp_id}/client-setupRead client setup/mcps/{mcp_id}/connect-linksIssue an OAuth connect link/mcps/{mcp_id}/connectionRead connection state/mcps/{mcp_id}/custom-toolsList an MCP's custom tools/mcps/{mcp_id}/custom-tools/{name}Delete a custom tool/mcps/{mcp_id}/custom-tools/{name}Read a custom tool/mcps/{mcp_id}/custom-tools/{name}Change a custom tool/mcps/{mcp_id}/custom-tools/{name}Create or replace a custom tool/mcps/{mcp_id}/custom-tools/{name}/restoreRestore an earlier version/mcps/{mcp_id}/custom-tools/{name}/versionsList a custom tool's saved versions/mcps/{mcp_id}/custom-tools:functionsList the functions a script can call/mcps/{mcp_id}/custom-tools:testTest-run a custom tool/mcps/{mcp_id}/custom-tools:validateCheck a custom tool definition/mcps/{mcp_id}/oauth-clientRead an MCP's OAuth client/mcps/{mcp_id}/oauth-clientRotate an MCP's OAuth client/mcps/{mcp_id}/oauth-scope-optionsRead OAuth permission options/mcps/{mcp_id}/scoped-settingsList per-user and per-group overrides/mcps/{mcp_id}/scoped-settings/{scope_type}/{scope_value}Remove an override/mcps/{mcp_id}/scoped-settings/{scope_type}/{scope_value}Create or replace an override/mcps/{mcp_id}/settingsRead MCP settings/mcps/{mcp_id}/settingsUpdate MCP settings/mcps/{mcp_id}/sign-in-linkGet the user sign-in link/mcps/{mcp_id}/tokensList MCP API tokens/mcps/{mcp_id}/tokensIssue an MCP API token/mcps/{mcp_id}/tokens/{token_id}Revoke an MCP API token/mcps/{mcp_id}/tool-changesRead tool-change state/mcps/{mcp_id}/tool-changes/applyAdopt the reviewed upstream tool list/mcps/{mcp_id}/tool-changes/checkCheck for tool changes now/mcps/{mcp_id}/tool-changes/dismissDismiss a tool change/mcps/{mcp_id}/tool-reviewsRead tool reviews/mcps/{mcp_id}/tool-reviews/approveApprove held tools/mcps/{mcp_id}/tool-reviews/rejectReject held tools/mcps/{mcp_id}/toolsList an MCP's tools/mcps/{mcp_id}/upstream-authRemove upstream credentials/mcps/{mcp_id}/upstream-authRead upstream credential metadata/mcps/{mcp_id}/upstream-authSet or rotate upstream credentials/mcps/{mcp_id}/usageUsage report for one MCP/mcps/{mcp_id}/usersList users of an MCP/mcps/{mcp_id}/users/{email}/connectionRevoke a user's connection/mcps:probeCheck an MCP URL/openapi.jsonDownload the OpenAPI document/operations/{op_id}Read an operation/requestsList tool calls/tenant/settingsRead tenant settings/tenant/settingsUpdate tenant settings/tool-arg-aliasesList tool-argument aliases/tool-arg-aliasesCreate a tool-argument alias/tool-arg-aliases/{alias_id}Delete a tool-argument alias/tool-arg-aliases/{alias_id}Read a tool-argument alias/tool-arg-aliases/{alias_id}Enable, disable or annotate an alias/tool-arg-aliases/{alias_id}Create or replace a tool-argument alias/tool-changesList tool-change state/usageUsage report/user-connectionsList users/user-connections/{email}Read a user's MCP connections/usersPer-user activityQuick start
This workflow checks access, lists MCPs, adds one, changes a setting, connects an OAuth MCP and reads a usage report. To try the same steps without a terminal, paste your key into the MCP Management API playground.
1. Prepare access
Send management requests to your MCP Gateway host, the same host your MCP endpoint URLs use, for example https://mcpgateway.quilr.ai. If your organization uses a regional or self-hosted MCP Gateway, use that host. Reports cover tool calls made through the gateway you call.
An administrator of your organization issues the key on the Management API tab under Settings > AI Gateway > MCP Gateway (see Enable in the console). For this workflow, the key needs read, mcps:write, settings:write and credentials:write.
You do not need your tenant ID for these calls: the key belongs to one tenant, and every call acts on that tenant. Only the administration endpoints take a tenant ID in the path; if you use them and do not have it, ask QuilrAI support.
export GW='https://mcpgateway.quilr.ai' # your MCP Gateway host
export KEY='<management-key>' # starts with qmcpmgmt_
Keep secrets in your automation secret store. These example values are placeholders, not live credentials.
Check the URL and key with a read-only call:
curl --fail-with-body "$GW/mcpgateway/management/v1/capabilities" \
--header "Authorization: Bearer $KEY"
A 200 response lists every scope, your key's own scopes in caller.scopes, limits, settings sections, authentication types, connection states, create options and analytics dimensions. If it fails:
2. List MCPs
curl "$GW/mcpgateway/management/v1/mcps?limit=50" \
--header "Authorization: Bearer $KEY"
{
"items": [
{
"id": "a1b2c3d4", "slug": "files", "name": "Files", "enabled": true,
"transport_type": "http", "execution_type": "remote",
"endpoint_urls": {"mcp": "https://mcpgateway.example.com/files/mcp"},
"upstream_host": "https://files.example.com", "auth_type": "api_key",
"oauth_mode": null, "source": "custom", "tool_count": 12,
"connection_state": "ready", "created_at": "2026-11-02T09:15:00Z", "version": "r4"
}
],
"next_cursor": null,
"request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f"
}
Responses never include upstream credentials, URL query strings or extra header values.
3. Add an MCP
curl --request POST "$GW/mcpgateway/management/v1/mcps" \
--header "Authorization: Bearer $KEY" \
--header 'Idempotency-Key: add-files-mcp-1' \
--header 'Content-Type: application/json' \
--data '{"name": "Files", "transport": "https://files.example.com/mcp",
"auth": {"type": "static", "token": "<api key>", "header_name": "X-Api-Key"},
"settings": {"dlp": {"data_risk_action": "redact"}}}'
This body carries a credential and settings, so the key needs credentials:write and settings:write in addition to mcps:write (see conditional scopes). The 201 response is {"mcp": {...}, "warnings": [...], "operation_id": "...", "connection": {...}}, plus connect for an OAuth MCP that needs a connect link.
To check what a URL needs before adding it, call POST /mcps:probe. See the MCPs API for every way to add an MCP.
4. Change settings with If-Match
Read the settings to get the current version (the ETag header), then send it back in If-Match:
curl --include "$GW/mcpgateway/management/v1/mcps/a1b2c3d4/settings" \
--header "Authorization: Bearer $KEY"
# ETag: "r4"
curl --request PATCH "$GW/mcpgateway/management/v1/mcps/a1b2c3d4/settings" \
--header "Authorization: Bearer $KEY" \
--header 'If-Match: "r4"' \
--header 'Content-Type: application/json' \
--data '{"tools": {"delete_file": {"enabled": false}, "write_file": {"enforce_confirmation": true}}}'
If someone changed the MCP since your read, in the console or through the API, the PATCH answers 412 version_conflict. Read again and retry.
5. Connect an OAuth MCP
Creating an OAuth MCP (auth.type oauth_dcr or oauth_login) returns connection.state: "pending_connection" and a connect link:
"connect": {"url": "https://mcpgateway.example.com/mcpgateway/management-connect#t=<token>",
"expires_at": "2026-11-14T10:15:00Z"}
The link is single-use and valid for 15 minutes. Whoever opens it is sent to the provider's sign-in, and the connection is saved for the administrator who issued the management key. No Quilr sign-in is needed.
Anyone who opens the link can complete the connection. Share it only with the person who should connect, over a private channel.
See Connect links for the full flow.
6. Read a usage report
curl "$GW/mcpgateway/management/v1/usage?from=2026-11-01&to=2026-11-08&granularity=day&group_by=mcp" \
--header "Authorization: Bearer $KEY"
{
"from": "2026-11-01T00:00:00Z", "to": "2026-11-09T00:00:00Z", "timezone": "UTC",
"granularity": "day", "group_by": ["mcp"],
"totals": {"requests": 1840, "success": 1801, "errors": 31, "blocked": 8, "unique_users": 37},
"rows": [{"period_start": "2026-11-01T00:00:00Z", "mcp": "a1b2c3d4", "mcp_name": "Files", "requests": 260}],
"row_count": 8, "next_cursor": null,
"generated_at": "2026-11-14T09:00:02Z", "data_through": "2026-11-09T00:00:00Z",
"request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f"
}
Abbreviated: report rows carry more fields. See the Analytics and audit API.
Next steps
Authentication and management keys
Two gates control access: management must be enabled for the organization, and each request must carry a valid management key. Every management key belongs to exactly one tenant; one tenant can have several keys for independent automation clients.
Request authentication
Authorization: Bearer <management-key>
Management keys start with qmcpmgmt_. The key establishes the tenant: MCPs of other tenants answer 404. Management keys, MCP client credentials and log export keys are not interchangeable.
Key lifecycle
- An administrator turns on Allow management keys for this organization on the Management API tab.
- The administrator issues a named key with explicit scopes and, optionally, an expiry.
- Store the returned secret. Issue a replacement key before revoking a key that an integration still uses.
Turning management off suspends every key: each answers 403 management_disabled_for_tenant until management is turned on again. Keys that are still unexpired and unrevoked then work again.
Writes made with a key act as the administrator who issued it. Audit events record that administrator, the key id and via: management_api. If the administrator leaves the organization, the key's writes, and reads made on that administrator's behalf, fail with 409 key_owner_unavailable; issue a new key.
Keys have no expiry unless you set one. Revoking a key is immediate and permanent. Revoked and expired keys cannot be changed (409 terminal_key_state); issue a new key instead.
Scopes
All scopes listed for an operation are required. No scope implies another.
Allowing or blocking an agent on an MCP (PUT /mcps/{mcp_id}/agents/{agent}) changes MCP configuration and needs settings:write.
GET /capabilities returns the calling key's scopes in caller.scopes, so a tool can hide actions it cannot perform.
Conditional scopes
Some operations need extra scopes depending on what the body carries. The OpenAPI document lists them in x-conditional-scopes.
A request missing a scope is refused with 403 insufficient_scope and error.required_scopes before anything is written. Scopes are checked again just before a write, so a key that is revoked or narrowed while its request waits is refused.
Administration endpoints
Most organizations manage keys in the console. The same actions are available over HTTP under /mcpgateway/management-admin/v1, authenticated with Authorization: Bearer <tenant administrator token>, the signed Quilr console token of an administrator of that tenant. The tenant_id in the path must be the administrator's tenant (403 tenant_access_required otherwise). A management key cannot call these endpoints (401 invalid_admin_token), and an administrator token cannot call the resource endpoints (401 invalid_management_key).
Tenant settings control {"enabled": true}. Key lists return metadata only, never secrets. Key issuance requires an Idempotency-Key: retrying the same request with the same key within 24 hours returns the same key and secret instead of issuing a second one. Changing or revoking a key, and changing tenant settings, require If-Match with the current version.
/admin/tenants/{tenant_id}/keysList management keys
Every management key of the tenant (active, expired and revoked), without secrets.
Tenant administrator tokenPath, query & header parameters 3
tenant_id (path)stringrequiredYour tenant id; must be the administrator's tenant.
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-admin/v1/tenants/tenant-123/keys?limit=50' \
--header 'Authorization: Bearer <tenant-admin-token>'
/admin/tenants/{tenant_id}/keysIssue a management key
Issues a key owned by the calling administrator; writes made with the key act as that administrator. The secret is returned once in `key.secret`. Requires management to be enabled for the tenant. Requires an Idempotency-Key; retrying with the same key and body within 24 hours returns the original response, a different body under the same key is 409 `idempotency_conflict`.
Tenant administrator tokenPath, query & header parameters 2
tenant_id (path)stringrequiredYour tenant id; must be the administrator's tenant.
Idempotency-Key (header)stringrequiredClient-chosen token (1 to 200 characters) that makes retries safe: the same token and body within 24 hours returns the original response.
Full request body specification application/json
expires_atstring | nulloptionalFuture RFC 3339 time with a timezone; null never expires.
namestringrequiredDisplay name.
scopesarray<string>requiredArray item specification
stringValues: "agents:write""connections:write""credentials:write""mcps:write""read""settings:write""tenant_settings:write""tokens:write""tool_reviews:write""tools:write"
Unknown fields are rejected in this object.
curl --request POST \
'https://mcpgateway.quilr.ai/mcpgateway/management-admin/v1/tenants/tenant-123/keys' \
--header 'Authorization: Bearer <tenant-admin-token>' \
--header 'Idempotency-Key: create-files-mcp-2026-11-14' \
--header 'Content-Type: application/json' \
--data '{
"expires_at": "2027-01-01T00:00:00Z",
"name": "CI automation",
"scopes": [
"read",
"mcps:write",
"settings:write"
]
}'
/admin/tenants/{tenant_id}/keys/{key_id}Revoke a management key
Revokes the key immediately and permanently. Send the quoted `version` from the latest read in If-Match (428 when missing, 412 when stale).
Tenant administrator tokenPath, query & header parameters 3
tenant_id (path)stringrequiredYour tenant id; must be the administrator's tenant.
key_id (path)stringrequiredManagement key id.
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-admin/v1/tenants/tenant-123/keys/0f8e7d6c-5b4a-4392-8170-6f5e4d3c2b1a' \
--header 'Authorization: Bearer <tenant-admin-token>' \
--header 'If-Match: "r4"'
/admin/tenants/{tenant_id}/keys/{key_id}Read a management key
Key metadata, never the secret.
Tenant administrator tokenPath, query & header parameters 2
tenant_id (path)stringrequiredYour tenant id; must be the administrator's tenant.
key_id (path)stringrequiredManagement key id.
No request body.
curl --request GET \
'https://mcpgateway.quilr.ai/mcpgateway/management-admin/v1/tenants/tenant-123/keys/0f8e7d6c-5b4a-4392-8170-6f5e4d3c2b1a' \
--header 'Authorization: Bearer <tenant-admin-token>'
/admin/tenants/{tenant_id}/keys/{key_id}Update a management key
Changes the name, scopes or expiry of an active key. Narrowed scopes apply to requests already waiting. Revoked and expired keys cannot be changed (409 `terminal_key_state`). Send the quoted `version` from the latest read in If-Match (428 when missing, 412 when stale).
Tenant administrator tokenPath, query & header parameters 3
tenant_id (path)stringrequiredYour tenant id; must be the administrator's tenant.
key_id (path)stringrequiredManagement key id.
If-Match (header)stringrequiredQuoted `version` (ETag) from the latest read of this resource.
Full request body specification application/json
expires_atstring | nulloptionalFuture RFC 3339 time with a timezone; null never expires.
namestringoptionalDisplay name.
scopesarray<string>optionalArray item specification
stringValues: "agents:write""connections:write""credentials:write""mcps:write""read""settings:write""tenant_settings:write""tokens:write""tool_reviews:write""tools:write"
Unknown fields are rejected in this object.
curl --request PATCH \
'https://mcpgateway.quilr.ai/mcpgateway/management-admin/v1/tenants/tenant-123/keys/0f8e7d6c-5b4a-4392-8170-6f5e4d3c2b1a' \
--header 'Authorization: Bearer <tenant-admin-token>' \
--header 'If-Match: "r4"' \
--header 'Content-Type: application/json' \
--data '{
"scopes": [
"read"
]
}'
/admin/tenants/{tenant_id}/settingsRead tenant management settings
Whether management keys may be used for this tenant.
Tenant administrator tokenPath, query & header parameters 1
tenant_id (path)stringrequiredYour tenant id; must be the administrator's tenant.
No request body.
curl --request GET \
'https://mcpgateway.quilr.ai/mcpgateway/management-admin/v1/tenants/tenant-123/settings' \
--header 'Authorization: Bearer <tenant-admin-token>'
/admin/tenants/{tenant_id}/settingsEnable or suspend management
Enables management for the tenant, or suspends it (every key then answers 403 `management_disabled_for_tenant` until it is enabled again). Send the quoted `version` from the latest read in If-Match (428 when missing, 412 when stale).
Tenant administrator tokenPath, query & header parameters 2
tenant_id (path)stringrequiredYour tenant id; must be the administrator's tenant.
If-Match (header)stringrequiredQuoted `version` (ETag) from the latest read of this resource.
Full request body specification application/json
enabledbooleanrequiredUnknown fields are rejected in this object.
curl --request PATCH \
'https://mcpgateway.quilr.ai/mcpgateway/management-admin/v1/tenants/tenant-123/settings' \
--header 'Authorization: Bearer <tenant-admin-token>' \
--header 'If-Match: "r4"' \
--header 'Content-Type: application/json' \
--data '{
"enabled": true
}'
API conventions and errors
Responses
- Every JSON response carries
request_id, also in theX-Request-IDheader. Quote it when contacting support. - Every response has
Cache-Control: no-store. - Timestamps are UTC RFC 3339 with a
Zsuffix. - Responses may gain fields over time; ignore fields you do not know.
- All bodies are JSON (
Content-Type: application/json).
Versions and If-Match
Resources that can be changed carry version, also returned as the ETag header. The operations listed below require If-Match with that quoted value:
- Missing:
428 precondition_required. - Stale:
412 version_conflict. Read again, reapply your change and retry.
An MCP has one configuration version (r<N>) shared by its name, enabled state, settings, overrides and upstream credentials, so a change to any of them changes the ETag for all of them. Live values (tool counts, connection state, usage) never change the version.
These operations take If-Match:
PATCHandDELETE /mcps/{mcp_id}PATCH /mcps/{mcp_id}/settingsPUTandDELETE /mcps/{mcp_id}/scoped-settings/{scope_type}/{scope_value}PUTandDELETE /mcps/{mcp_id}/upstream-authPUT /mcps/{mcp_id}/agents/{agent}PUT /mcps/{mcp_id}/oauth-clientPATCH /mcps/{mcp_id}/api-config, andPOST /mcps/{mcp_id}/api-config/resync?apply=true(optional withoutapply=true)PUT,PATCHandDELETE /mcps/{mcp_id}/custom-tools/{name}, andPOST /mcps/{mcp_id}/custom-tools/{name}/restorePOST /mcps/{mcp_id}/tool-changes/applyandPOST /mcps/{mcp_id}/tool-changes/dismiss(the pending change'sversion, see Tool changes)PATCH /tenant/settings(the tenant settingsversion)- the administration
PATCH .../settingsandPATCH/DELETE .../keys/{key_id}
These do not take If-Match: tool review approve and reject, MCP API token revoke, agent delete, alias PUT, PATCH and DELETE, MCP request dismiss, user connection revoke, and tool change check.
Idempotency and recovery
Creates require an Idempotency-Key header, 1 to 200 characters of your choosing, without control characters: POST /mcps, POST /mcps/api, POST /catalog/{catalog_id}/install, POST /mcps/{mcp_id}/tokens and administration key issuance.
Custom tool test runs (POST /mcps/{mcp_id}/custom-tools:test) take an optional Idempotency-Key with the same rules: once the script has started, the same key and body within 24 hours return the stored answer instead of running the tool again. A run that certainly did not run the tool is not stored, so a retry with the same key runs it.
If a create is interrupted, the response may be 503 operation_pending with operation_id. Retry the same request with the same Idempotency-Key: the gateway finishes or cleanly redoes it and never creates a duplicate. GET /operations/{op_id} shows its state; only the key that started the operation can read it. Concurrent creates of the same name answer 409 operation_in_progress; an existing slug answers 409 slug_conflict.
Pagination
List endpoints take limit (1 to 200, default 50) and cursor. Pass the next_cursor of the previous page; it is null on the last page. If the list changes between pages you get 409 collection_changed; start again without a cursor. Analytics reports use their own limits (see Analytics).
Query parameters and limits
- Each endpoint accepts only its documented query parameters, each at most once. Anything else is
400 invalid_request. - Unknown body fields, at any depth, are refused with
400and their paths inerror.fields. - Bodies are at most 1 MiB (
413 body_too_large) and must arrive within 10 seconds (408 body_timeout). An inline OpenAPI document grows when it is JSON-escaped (spec_text) or base64-encoded (spec_base64), so a document over about 750 KB does not fit: give it assource_urlinstead. - At most 32 management requests are in flight per gateway, and one organization may use at most half of them. Beyond either limit you get
429 management_busywithRetry-After; other organizations' calls are still admitted.
Errors
Every error has the same shape:
{
"error": {
"code": "invalid_request",
"message": "Unknown or unsupported fields: body.foo",
"fields": ["body.foo"]
},
"request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f"
}
message is fixed text. fields names the offending request paths (body.x, query.y, path.z) and never echoes submitted values. Analytics reports return fields as an object keyed by query parameter with the reason instead, for example {"from": "from and to may be at most 92 days apart"}. Some errors add details such as required_scopes, operation_id, current_version, missing_fields, may_have_run or tool_changes.
Retry guidance: 429 and 503 are safe to retry after Retry-After, except data_unavailable on a deployment without an analytics store. Retry creates only with the same Idempotency-Key. On 412, read the resource again before retrying. A 502 test_run_failed with "may_have_run": true may have run the tool: check the MCP's logs before running it again with a new key; with false nothing ran and a retry is safe.
OpenAPI document
The gateway serves its OpenAPI 3.1 document at GET /mcpgateway/management/v1/openapi.json (management key with read). The body is the bare document, without request_id.
curl "$GW/mcpgateway/management/v1/openapi.json" \
--header "Authorization: Bearer $KEY" > mcp-management-v1.json
The document is generated from the deployed routes, so it always matches the API your gateway runs, and it lists exactly one server: your gateway. You can also download a copy from this site. Each operation carries:
x-scopes: the scopes it always requires (empty on Administration endpoints, which take a tenant administrator token).x-conditional-scopes: scopes added by body content, with the condition.If-MatchandIdempotency-Keyheader parameters where required.- Request and response schemas with examples, and the standard error responses.
When you import the document into an API gateway, turn off upstream retries for non-GET methods: creates are safe to retry only with the same Idempotency-Key. Pass Authorization, If-Match and Idempotency-Key through unchanged, and keep the ETag, Retry-After and X-Request-ID response headers.
/capabilitiesRead capabilities
What this deployment supports: every scope, the calling key's id and scopes (`caller`), limits, settings sections, authentication types, connection states, create options and analytics dimensions. Use it to build forms and to hide actions the caller cannot perform.
readNo request body.
curl --request GET \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/capabilities' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Scopes Try it in the playground
/openapi.jsonDownload the OpenAPI document
This OpenAPI 3.1 document, generated by the server from its route table so it always matches the deployed API. Requires the read scope. The body is the bare document (no request_id field).
readNo request body.
curl --request GET \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/openapi.json' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Scopes Try it in the playground
/operations/{op_id}Read an operation
Status of a journaled create (MCP create, catalog install, REST API MCP create) by its `operation_id`: state pending, done, failed or expired, the created resource id and the completed stages. Only the key that started the operation can read it. A pending operation is completed by retrying the original request with the same Idempotency-Key.
readPath, query & header parameters 1
op_id (path)stringrequiredOperation id returned by a create (`operation_id`).
No request body.
curl --request GET \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/operations/5b1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Scopes Try it in the playground