Skip to main content

MCP Gateway Management API

MCP GATEWAY / MANAGEMENT V1

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.

Tenant-bound keys Explicit scopes Same rules as the console

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​

  1. Go to Settings > AI Gateway > MCP Gateway and open the Management API tab (next to Servers).
  2. 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.
  3. Under Issue a management key, enter a Key name, an optional Expiry (leave blank for no expiry), and the scopes the key needs.
  4. 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.
Console scopeAPI scopeGrants
ReadreadRead MCPs, settings, analytics and audit.
Manage MCPsmcps:writeAdd, install, rename, enable/disable and delete MCPs.
Change settingssettings:writeChange MCP settings and scoped overrides.
Set credentialscredentials:writeSet upstream credentials and OAuth client secrets.
Review toolstool_reviews:writeApprove or reject new tools and upstream tool changes.
Issue MCP tokenstokens:writeIssue and revoke MCP API tokens for clients.
Revoke connectionsconnections:writeRevoke a user's stored credentials for an MCP.
Manage agentsagents:writeCreate and delete custom agents.
Tenant settingstenant_settings:writeChange tenant switches, tool-argument aliases and MCP requests.
Custom toolstools:writeCreate, change, delete and test-run custom tools. Test runs call the MCP as the key owner.

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​

The management model​

Enable
Organization opt-in
Console Management API tab
Authorize
One tenant per key
Explicit scopes
Change
Versioned writes
Validated settings
Apply
Direct MCP endpoints
OneMCP
QuilrAI
ResourceWhat you can doWhat stays separate
MCPsList, read, add by URL, add a REST API as an MCP, rename, enable, disable and remove. Check a URL before adding it. List each MCP's tools, resources and prompts. See the MCPs API.MCPs provided by Quilr can be disabled, not removed.
MCP LibraryBrowse the catalog with your install state and install prebuilt MCPs. See the MCP Library.Each catalog MCP installs once per organization.
SettingsTools, DLP, token saving, access control, web search policy, tool sync, tool exposure, OneMCP and more, plus per-user and per-smart-group overrides. See the Settings and credentials API.Under QuilrQL policies, settings are saved but not enforced.
Upstream credentialsSet, rotate and remove the static credential and extra headers or query parameters the gateway sends upstream.Secrets are write-only and never returned. OAuth MCPs connect through connect links.
Tool reviewsApprove or reject new upstream tools held for review.
ConnectionsRead connection state, fetch tools now, and issue single-use OAuth connect links. See the Connections and OAuth API.OAuth passthrough MCPs need no link: each client brings its own token.
AnalyticsTool calls, outcomes, latency, DLP activity, tool-call metadata and per-user activity. See the Analytics and audit API.Metadata only: never tool arguments, responses or tokens. Bulk logs come from the Log Export API.
AuditConfiguration changes made in the console and through this API, newest first.Never before or after values.

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 settings or "enabled": false adds 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

GET
/admin/tenants/{tenant_id}/keysList management keys
POST
/admin/tenants/{tenant_id}/keysIssue a management key
DELETE
/admin/tenants/{tenant_id}/keys/{key_id}Revoke a management key
GET
/admin/tenants/{tenant_id}/keys/{key_id}Read a management key
PATCH
/admin/tenants/{tenant_id}/keys/{key_id}Update a management key
GET
/admin/tenants/{tenant_id}/settingsRead tenant management settings
PATCH
/admin/tenants/{tenant_id}/settingsEnable or suspend management
GET
/agentsList agents
POST
/agentsCreate a custom agent
DELETE
/agents/{keyword}Delete a custom agent
GET
/agents/{keyword}Read an agent
GET
/api-access/presetsList access rule presets
POST
/api-access/testTest candidate access rules
GET
/auditList audit events
GET
/capabilitiesRead capabilities
GET
/catalogList the MCP Library
GET
/catalog/{catalog_id}Read a catalog entry
POST
/catalog/{catalog_id}/installInstall a catalog MCP
GET
/dlp/summaryDLP summary
GET
/latencyLatency report
GET
/mcp-requestsList users' MCP requests
POST
/mcp-requests/{request_id}/dismissDismiss an MCP request
GET
/mcpsList MCPs
POST
/mcpsAdd a remote MCP
POST
/mcps/apiAdd a REST API as an MCP
POST
/mcps/api:previewPreview a REST API spec
DELETE
/mcps/{mcp_id}Remove an MCP
GET
/mcps/{mcp_id}Read an MCP
PATCH
/mcps/{mcp_id}Rename, describe, enable or disable an MCP
GET
/mcps/{mcp_id}/agentsRead which agents may use an MCP
PUT
/mcps/{mcp_id}/agents/{agent}Allow or block an agent on an MCP
GET
/mcps/{mcp_id}/api-configRead a REST API MCP's configuration
PATCH
/mcps/{mcp_id}/api-configChange a REST API MCP's configuration
POST
/mcps/{mcp_id}/api-config/access-testTest the saved access rules
POST
/mcps/{mcp_id}/api-config/resyncResync the OpenAPI document
POST
/mcps/{mcp_id}/api-config/selection-previewPreview which operations would become tools
POST
/mcps/{mcp_id}/capabilities:refreshRefresh tools
GET
/mcps/{mcp_id}/client-setupRead client setup
POST
/mcps/{mcp_id}/connect-linksIssue an OAuth connect link
GET
/mcps/{mcp_id}/connectionRead connection state
GET
/mcps/{mcp_id}/custom-toolsList an MCP's custom tools
DELETE
/mcps/{mcp_id}/custom-tools/{name}Delete a custom tool
GET
/mcps/{mcp_id}/custom-tools/{name}Read a custom tool
PATCH
/mcps/{mcp_id}/custom-tools/{name}Change a custom tool
PUT
/mcps/{mcp_id}/custom-tools/{name}Create or replace a custom tool
POST
/mcps/{mcp_id}/custom-tools/{name}/restoreRestore an earlier version
GET
/mcps/{mcp_id}/custom-tools/{name}/versionsList a custom tool's saved versions
GET
/mcps/{mcp_id}/custom-tools:functionsList the functions a script can call
POST
/mcps/{mcp_id}/custom-tools:testTest-run a custom tool
POST
/mcps/{mcp_id}/custom-tools:validateCheck a custom tool definition
GET
/mcps/{mcp_id}/oauth-clientRead an MCP's OAuth client
PUT
/mcps/{mcp_id}/oauth-clientRotate an MCP's OAuth client
GET
/mcps/{mcp_id}/oauth-scope-optionsRead OAuth permission options
GET
/mcps/{mcp_id}/scoped-settingsList per-user and per-group overrides
DELETE
/mcps/{mcp_id}/scoped-settings/{scope_type}/{scope_value}Remove an override
PUT
/mcps/{mcp_id}/scoped-settings/{scope_type}/{scope_value}Create or replace an override
GET
/mcps/{mcp_id}/settingsRead MCP settings
PATCH
/mcps/{mcp_id}/settingsUpdate MCP settings
GET
/mcps/{mcp_id}/sign-in-linkGet the user sign-in link
GET
/mcps/{mcp_id}/tokensList MCP API tokens
POST
/mcps/{mcp_id}/tokensIssue an MCP API token
DELETE
/mcps/{mcp_id}/tokens/{token_id}Revoke an MCP API token
GET
/mcps/{mcp_id}/tool-changesRead tool-change state
POST
/mcps/{mcp_id}/tool-changes/applyAdopt the reviewed upstream tool list
POST
/mcps/{mcp_id}/tool-changes/checkCheck for tool changes now
POST
/mcps/{mcp_id}/tool-changes/dismissDismiss a tool change
GET
/mcps/{mcp_id}/tool-reviewsRead tool reviews
POST
/mcps/{mcp_id}/tool-reviews/approveApprove held tools
POST
/mcps/{mcp_id}/tool-reviews/rejectReject held tools
GET
/mcps/{mcp_id}/toolsList an MCP's tools
DELETE
/mcps/{mcp_id}/upstream-authRemove upstream credentials
GET
/mcps/{mcp_id}/upstream-authRead upstream credential metadata
PUT
/mcps/{mcp_id}/upstream-authSet or rotate upstream credentials
GET
/mcps/{mcp_id}/usageUsage report for one MCP
GET
/mcps/{mcp_id}/usersList users of an MCP
DELETE
/mcps/{mcp_id}/users/{email}/connectionRevoke a user's connection
POST
/mcps:probeCheck an MCP URL
GET
/openapi.jsonDownload the OpenAPI document
GET
/operations/{op_id}Read an operation
GET
/requestsList tool calls
GET
/tenant/settingsRead tenant settings
PATCH
/tenant/settingsUpdate tenant settings
GET
/tool-arg-aliasesList tool-argument aliases
POST
/tool-arg-aliasesCreate a tool-argument alias
DELETE
/tool-arg-aliases/{alias_id}Delete a tool-argument alias
GET
/tool-arg-aliases/{alias_id}Read a tool-argument alias
PATCH
/tool-arg-aliases/{alias_id}Enable, disable or annotate an alias
PUT
/tool-arg-aliases/{alias_id}Create or replace a tool-argument alias
GET
/tool-changesList tool-change state
GET
/usageUsage report
GET
/user-connectionsList users
GET
/user-connections/{email}Read a user's MCP connections
GET
/usersPer-user activity

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

PathCredential
/mcpgateway/management/v1/...Management key
/mcpgateway/management-admin/v1/...Tenant administrator token (see Administration endpoints)

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:

ResponseMeaning
401 invalid_management_keyThe key is missing, wrong, expired or revoked.
403 insufficient_scopeThe key lacks read.
403 management_disabled_for_tenantAllow management keys for this organization is off.
404 not_foundThe URL or path is wrong, or management is turned off for this deployment.

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.

Treat a connect link like a password

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​

TaskReference
Install an MCP from the MCP LibraryInstall a catalog MCP
Expose a REST API as MCP toolsAdd a REST API as an MCP
Change which REST API operations become toolsREST API MCPs
Add your own tool that chains an MCP's toolsCustom tools
Give people a link to connect an MCP themselvesSign-in link
Have each person bring their own API keyUpstream credentials
Rotate an OAuth client secretOAuth client rotation
Override settings for one user or smart groupPer-user and per-group overrides
Rotate an upstream API keyUpstream credentials
Approve new toolsTool reviews
Give a client the endpoint and a tokenClient access
See who is connected, or make one user reconnectUser connections
Adopt or dismiss an upstream tool changeTool changes
Turn Memories or Dynamic Tool Calling on or offTenant settings
Reconnect an OAuth MCPConnect links
Build a usage or latency dashboardAnalytics
See who changed whatAudit
Try any call from the browserMCP Management API playground

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.

CredentialPurposeSecret retrieval
Management keyRead and change the organization's MCPs within the key's scopes.Shown once when issued; cannot be revealed later.
Tenant administrator tokenEnable management and issue, change or revoke management keys through the Administration endpoints.Follows your Quilr console sign-in.

Key lifecycle​

  1. An administrator turns on Allow management keys for this organization on the Management API tab.
  2. The administrator issues a named key with explicit scopes and, optionally, an expiry.
  3. 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.

ScopeAllows
readRead MCPs, tools, settings, credential metadata, tool reviews, connection state, the catalog, operations, the audit trail, analytics and the OpenAPI document.
mcps:writeCreate, rename, enable, disable and remove MCPs; install catalog MCPs; check MCP URLs; preview REST API specs; change and resync REST API configuration; refresh tools; issue OAuth connect links.
settings:writeChange MCP settings and per-user or per-smart-group overrides; send settings with a create.
credentials:writeSet or remove upstream credentials and extra headers or query parameters; rotate an MCP's OAuth client; any create, check or preview that carries credentials.
tool_reviews:writeApprove or reject tools held for review; check, adopt or dismiss upstream tool changes.
tokens:writeIssue and revoke MCP API tokens.
connections:writeRevoke a user's stored credentials for an MCP.
agents:writeCreate and delete custom agents.
tenant_settings:writeChange tenant switches (Dynamic Tool Calling, Memories, new-tool review), manage tool-argument aliases and dismiss users' MCP requests.
tools:writeCreate, change, delete and test-run custom tools. Test runs call the MCP as the key owner, with real effects.

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.

OperationAdds credentials:write whenAdds settings:write when
POST /mcpsauth has token, client_id, client_secret, extra_headers or extra_query_params, or transport has userinfo or a query stringsettings is present
POST /mcps:probeextra_headers or extra_query_params, or transport has userinfo or a query string
POST /catalog/{catalog_id}/installauth_token, oauth_client_id, oauth_client_secret, upstream_auth_extra_headers, upstream_auth_extra_query_params or transport_values
POST /mcps/apiauth_token or any upstream_auth_* field, nonempty openapi.overrides.*.fixed_params, or base_url or openapi.source_url with userinfo or a query stringsettings is present
POST /mcps/api:previewfetch_headers, or source_url with userinfo or a query string
PATCH /mcps/{mcp_id}/api-configthe body sends base_url or remote_connector_id (saved credentials go to that destination), nonempty openapi.overrides.*.fixed_params, or openapi.source_url with userinfo or a query string
POST /mcps/{mcp_id}/api-config/resyncfetch_headers

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.

GET/admin/tenants/{tenant_id}/keys

List management keys

Every management key of the tenant (active, expired and revoked), without secrets.

REQUIRESTenant administrator token
Path, query & header parameters 3
tenant_id (path)stringrequired

Your tenant id; must be the administrator's tenant.

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-admin/v1/tenants/tenant-123/keys?limit=50' \
--header 'Authorization: Bearer <tenant-admin-token>'

Authentication, errors & retry rules Scopes

POST/admin/tenants/{tenant_id}/keys

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

REQUIRESTenant administrator token
Path, query & header parameters 2
tenant_id (path)stringrequired

Your tenant id; must be the administrator's tenant.

Idempotency-Key (header)stringrequired

Client-chosen token (1 to 200 characters) that makes retries safe: the same token and body within 24 hours returns the original response.

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

expires_atstring | nulloptional

Future RFC 3339 time with a timezone; null never expires.

format: date-time
namestringrequired

Display name.

min length: 1max length: 200
scopesarray<string>required
min items: 1unique items
Array item specification
string

Values: "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"
]
}'

Authentication, errors & retry rules Scopes

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

REQUIRESTenant administrator token
Path, query & header parameters 3
tenant_id (path)stringrequired

Your tenant id; must be the administrator's tenant.

key_id (path)stringrequired

Management key id.

If-Match (header)stringrequired

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

Full request body specification application/json

No body, or an empty JSON object.

Unknown fields are rejected in this object.

curl --request DELETE \
'https://mcpgateway.quilr.ai/mcpgateway/management-admin/v1/tenants/tenant-123/keys/0f8e7d6c-5b4a-4392-8170-6f5e4d3c2b1a' \
--header 'Authorization: Bearer <tenant-admin-token>' \
--header 'If-Match: "r4"'

Authentication, errors & retry rules Scopes

GET/admin/tenants/{tenant_id}/keys/{key_id}

Read a management key

Key metadata, never the secret.

REQUIRESTenant administrator token
Path, query & header parameters 2
tenant_id (path)stringrequired

Your tenant id; must be the administrator's tenant.

key_id (path)stringrequired

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

Authentication, errors & retry rules Scopes

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

REQUIRESTenant administrator token
Path, query & header parameters 3
tenant_id (path)stringrequired

Your tenant id; must be the administrator's tenant.

key_id (path)stringrequired

Management key id.

If-Match (header)stringrequired

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

Full request body specification application/json

expires_atstring | nulloptional

Future RFC 3339 time with a timezone; null never expires.

format: date-time
namestringoptional

Display name.

min length: 1max length: 200
scopesarray<string>optional
min items: 1unique items
Array item specification
string

Values: "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"
]
}'

Authentication, errors & retry rules Scopes

GET/admin/tenants/{tenant_id}/settings

Read tenant management settings

Whether management keys may be used for this tenant.

REQUIRESTenant administrator token
Path, query & header parameters 1
tenant_id (path)stringrequired

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

Authentication, errors & retry rules Scopes

PATCH/admin/tenants/{tenant_id}/settings

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

REQUIRESTenant administrator token
Path, query & header parameters 2
tenant_id (path)stringrequired

Your tenant id; must be the administrator's tenant.

If-Match (header)stringrequired

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

Full request body specification application/json

enabledbooleanrequired

Unknown 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
}'

Authentication, errors & retry rules Scopes

API conventions and errors​

Responses​

  • Every JSON response carries request_id, also in the X-Request-ID header. Quote it when contacting support.
  • Every response has Cache-Control: no-store.
  • Timestamps are UTC RFC 3339 with a Z suffix.
  • 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:

  • PATCH and DELETE /mcps/{mcp_id}
  • PATCH /mcps/{mcp_id}/settings
  • PUT and DELETE /mcps/{mcp_id}/scoped-settings/{scope_type}/{scope_value}
  • PUT and DELETE /mcps/{mcp_id}/upstream-auth
  • PUT /mcps/{mcp_id}/agents/{agent}
  • PUT /mcps/{mcp_id}/oauth-client
  • PATCH /mcps/{mcp_id}/api-config, and POST /mcps/{mcp_id}/api-config/resync?apply=true (optional without apply=true)
  • PUT, PATCH and DELETE /mcps/{mcp_id}/custom-tools/{name}, and POST /mcps/{mcp_id}/custom-tools/{name}/restore
  • POST /mcps/{mcp_id}/tool-changes/apply and POST /mcps/{mcp_id}/tool-changes/dismiss (the pending change's version, see Tool changes)
  • PATCH /tenant/settings (the tenant settings version)
  • the administration PATCH .../settings and PATCH / 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.

SituationResult
Same key and same request within 24 hoursThe original response is returned: the same MCP, the same key secret. A connect link lives only 15 minutes and works once, so when the stored link has expired, was used, or has less than 60 seconds left, the replay carries a new link for the same MCP (only connect.url and connect.expires_at differ). Later retries return that new link while it is valid.
Same key with a different method, path or body409 idempotency_conflict
Same key after 24 hours409 idempotency_replay_expired; use a new key.
Missing header on a create, or a key over 200 characters or with control characters400 idempotency_key_required

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 400 and their paths in error.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 as source_url instead.
  • 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_busy with Retry-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.

StatusCodeMeaning
400invalid_requestInvalid body, path or query parameter (fields).
400idempotency_key_requiredCreate without a valid Idempotency-Key, or a malformed key on any request that takes one.
400invalid_configurationThe configuration was refused or conflicts with an existing MCP.
400upstream_auth_failedThe upstream MCP server rejected the credentials or could not list tools.
400oauth_registration_failedDynamic client registration with the provider failed (oauth_dcr without your own client); supply OAuth client credentials. Used only for that failure.
400no_operations_selected, invalid_operation_overrideA REST API change would expose no operation, or names operations not in the document (unknown_operations).
400spec_missing, spec_invalid, blocked_destinationOpenAPI document missing, unreadable, or at a destination the gateway does not call. OpenAPI document errors use the same codes on create, preview, PATCH .../api-config and resync.
400unsupported_encoding, invalid_api_backendThe OpenAPI document's encoding is not supported; the REST API configuration is invalid.
401invalid_management_keyMissing, unknown, expired or revoked key.
401invalid_admin_tokenAdministration endpoint without a valid administrator token.
403insufficient_scopeThe key lacks a scope (required_scopes).
403management_disabled_for_tenantManagement is turned off for the organization.
403tenant_access_required, admin_required, admin_identity_requiredAdministrator token for another tenant, not an administrator, or without an identity.
403system_mcpMCPs provided by Quilr cannot be removed.
403forbiddenOperation not permitted.
404not_foundUnknown resource or path, including MCPs of other tenants.
404connect_link_not_foundUnknown connect link.
404custom_tool_not_foundNo custom tool with that name on the MCP.
404custom_tool_version_not_foundNo saved version with that number in the custom tool's history.
405method_not_allowedThe path does not take this method.
408body_timeoutBody not received within 10 seconds.
409conflictConflicts with the current state.
409slug_conflict, already_installedName already taken; catalog MCP already installed.
409operation_in_progressAnother create of the same name is running.
409idempotency_conflict, idempotency_replay_expiredSee Idempotency and recovery.
409collection_changedThe list changed during pagination; restart.
409key_owner_unavailableThe key's administrator left the organization; issue a new key.
409terminal_key_stateRevoked or expired keys cannot change.
409policy_dependencyThe active QuilrQL policy depends on it.
409tools_not_awaiting_reviewA named tool is not held for review.
409tool_changes_unavailableTool-change apply: the upstream tool list cannot be read now; nothing was adopted. Retry later.
409oauth_mcp_uses_sign_inOAuth MCPs do not take MCP API tokens.
409token_revokedThe token was revoked before its interrupted issue completed; issue a new one.
409operation_not_pendingThe interrupted operation is no longer pending.
409key_conflictManagement key identity conflict; retry, or issue a new key.
409no_operations_selectedPOST /mcps/{mcp_id}/api-config/resync?apply=true would leave no operation selected.
409agent_exists, built_in_agentAgent keyword taken; built-in agents cannot be deleted.
409alias_id_in_use, request_not_pendingAlias id belongs to another organization; request already resolved.
409oauth_connection_requiredRefresh of an OAuth MCP the key's administrator has not connected.
409upstream_credential_requiredThe MCP needs a credential before tools can be fetched.
409pending_first_clientOAuth passthrough MCPs cannot be refreshed by the gateway.
409oauth_not_applicableThe MCP does not use gateway-managed OAuth.
409not_api_mcp, not_openapi, spec_uploadedNot a REST API MCP; not built from an OpenAPI document; the document was uploaded, so send a new one instead of resyncing.
409test_run_in_progressA custom tool test run with this Idempotency-Key is still running; retry after Retry-After. See retry safely.
409tool_name_taken, custom_tool_limit, test_run_unavailable, mcp_disabledOne of the MCP's own tools already uses the name; the MCP already has 50 custom tools; test runs are not available on OAuth passthrough MCPs; a test run on a disabled MCP. See custom tool errors.
409not_oauth_mcp, oauth_client_not_customNo gateway OAuth client; the gateway registered the client itself, so it cannot be rotated.
409connect_link_usedConnect link already used.
410goneThe resource is no longer available.
410connect_link_expiredConnect link expired.
410connect_link_revokedThe management key that issued the connect link was revoked or expired.
410preview_expiredThe OpenAPI preview expired; preview the document again.
412version_conflictIf-Match is stale (current_version when known; on tool-change apply and dismiss, tool_changes holds the current state, also when the change was applied or dismissed meanwhile).
412tool_changes_changedTool-change apply: upstream no longer serves the reviewed change, so nothing was adopted (tool_changes holds the new change).
413body_too_largeBody over 1 MiB.
413spec_too_largeThe OpenAPI document is over 10 MiB. An inline document is also bound by the 1 MiB body limit (body_too_large); send source_url instead.
422install_input_requiredCatalog install needs more values (missing_fields).
422result_too_largeReport would exceed 100,000 rows.
422tools_too_largeThe selected REST API operations produce more tool definitions than allowed.
428precondition_requiredIf-Match missing.
429management_busy, report_busy, rate_limitedToo many requests; honor Retry-After. management_busy can also mean your organization is over its share of concurrent management calls.
502upstream_unavailable, oauth_initiation_failedThe upstream MCP server or OAuth provider is unreachable or refused.
502fetch_failedThe OpenAPI document could not be downloaded.
502test_run_failedA custom tool test run failed before a result came back: may_have_run is true when the script started or the run never recorded an answer, false when nothing ran. See retry safely.
503operation_pendingCreate incomplete; retry with the same Idempotency-Key.
503storage_unavailable, service_unavailable, mcp_busyTemporary; retry after Retry-After.
503query_timeout, data_unavailableAnalytics temporarily unavailable. On a deployment without an analytics store, data_unavailable is permanent.
504upstream_timeoutThe upstream MCP server did not respond in time.

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-Match and Idempotency-Key header 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.

GET/capabilities

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

REQUIRESread

No 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

GET/openapi.json

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

REQUIRESread

No 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

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

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

Operation 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