Skip to main content

MCPs API

An MCP is an MCP server the gateway serves to your organization. Clients connect to its endpoint_urls.mcp (https://<gateway>/<slug>/mcp) or through OneMCP. Address an MCP by its id within the key's tenant; MCPs of other tenants answer 404. Try these operations with your own key in the MCP Management API playground.

Each MCP has a source:

SourceWhat it isRemoval
customAdded by URL.DELETE removes it.
catalogInstalled from the MCP Library.DELETE uninstalls it.
apiA REST API exposed as MCP tools. See API to MCP.DELETE removes it.
systemProvided by Quilr.Cannot be removed (403 system_mcp); disable it instead.

List and inspect MCPs​

GET /mcps returns enabled and disabled MCPs, sorted by name. Filter with name (case-insensitive substring), slug, enabled, auth_type (api_key, no_auth, oauth or oauth_passthrough), transport_type (http or sse) and source. The listed auth_type maps from the create auth.type: static lists as api_key, none as no_auth, and oauth_dcr and oauth_login as oauth. tool_count and connection_state are live values; they never invalidate a cursor.

GET /mcps/{mcp_id} returns one MCP with its last tool-fetch errors (fixed codes, never upstream text) and its version, the ETag of the MCP configuration. GET /mcps/{mcp_id}/tools lists cached tools, resources and prompts. Each tool carries its enabled and confirmation settings, its review state (held or rejected tools are listed too) and its all-time call count.

Responses never include upstream credentials, URL query strings or extra header values.

Add an MCP​

There are three ways to add an MCP. All three are creates: send an Idempotency-Key header (see idempotency and recovery).

OperationUse it to
POST /mcpsAdd a remote MCP server by URL (Streamable HTTP or SSE).
POST /catalog/{catalog_id}/installInstall a prebuilt MCP from the MCP Library. See MCP Library.
POST /mcps/apiExpose a REST API as MCP tools. Preview its OpenAPI document first with POST /mcps/api:preview and pass the returned preview_token. Change it later with the REST API MCPs API.

Before adding a remote MCP, POST /mcps:probe with {"transport": "<url>"} reports the transport, OAuth discovery results and whether a credential is required, without saving anything. Use it to choose auth.type.

To reach a server on a private network, pass remote_connector_id with the Remote Connector to use. slug sets the endpoint path and defaults to one derived from the name.

Upstream authentication​

auth.type selects how the gateway authenticates to the upstream server:

auth.typeBehavior
noneNo upstream credential.
staticAn API key or token: sent as a bearer token by default, in header_name, or in query_param.
oauth_dcrOAuth with dynamic client registration. With your own client_id and client_secret it skips registration and is saved like oauth_login with that client (the MCP then reports oauth_mode: "login").
oauth_loginOAuth with your registered client (client_id and client_secret) or a provider-issued client.
oauth_passthroughEach MCP client brings its own OAuth token.

For a public OAuth client, one registered without a secret, send "client_secret": "-". The same "-" works for oauth_client_secret on a catalog install and for client_secret when you rotate the client:

curl --request POST "$GW/mcpgateway/management/v1/mcps" \
--header "Authorization: Bearer $KEY" \
--header 'Idempotency-Key: add-tracker-mcp-1' \
--header 'Content-Type: application/json' \
--data '{"name": "Tracker", "transport": "https://tracker.example.com/mcp",
"auth": {"type": "oauth_login", "client_id": "<public client id>", "client_secret": "-"}}'

Credentials set when adding an MCP are shared by all users of the organization; to have each person bring their own key, switch the MCP's upstream credential mode afterwards. A body that carries credentials also needs credentials:write, and one that carries settings also needs settings:write (see conditional scopes).

OAuth MCPs (oauth_dcr and oauth_login) are created with connection.state pending_connection and a single-use connect link. See Connect links. If dynamic client registration with the provider fails (oauth_dcr without your own client), the create answers 400 oauth_registration_failed: register a client with the provider and send its client_id and client_secret. oauth_passthrough MCPs need no link: their tools appear when the first client connects with its own token.

Settings and state on create​

POST /mcps and POST /mcps/api accept settings and enabled; a catalog install takes neither, so change them after it. They apply before the MCP is returned. A create that carries settings or "enabled": false adds the MCP disabled, applies the settings, and sets the requested state last. An interrupted create therefore never leaves the MCP usable without its settings: it stays disabled until a retry with the same Idempotency-Key completes.

REST API MCP document errors​

POST /mcps/api and POST /mcps/api:preview read an OpenAPI document from preview_token, source_url, spec_text or spec_base64. Request bodies are limited to 1 MiB, and an inline document grows when it is JSON-escaped or base64-encoded, so give a document over about 750 KB as source_url. Document problems answer with the same codes here and on PATCH .../api-config and resync:

StatusCodeMeaning
400spec_missingNo document, or more than one source.
400spec_invalidThe document could not be read as OpenAPI.
400blocked_destinationsource_url points to a destination the gateway does not call, such as a private or reserved network address.
410preview_expiredThe preview_token expired; preview the document again.
413spec_too_largeThe document is over 10 MiB.
422tools_too_largeThe selected operations produce more tool definitions than allowed.
502fetch_failedThe document could not be downloaded from source_url. Nothing was created; fix the URL or headers and retry.

Change and remove an MCP​

PATCH /mcps/{mcp_id} changes name, description and enabled. Disabling stops serving the MCP to every client until it is enabled again.

DELETE /mcps/{mcp_id} removes a custom or REST API MCP, or uninstalls a catalog MCP, together with its stored credentials and settings. MCPs provided by Quilr answer 403 system_mcp; disable them with PATCH {"enabled": false} instead. An MCP the active QuilrQL policy references answers 409 policy_dependency.

Both need If-Match with the MCP's current version (see versions and If-Match).

MCP Library​

GET /catalog lists catalog MCPs with your organization's install state. Filter with query (search), install_status and auth_type. install_requirements lists the values an install needs.

POST /catalog/{catalog_id}/install installs a catalog MCP once per organization (409 already_installed after that). Supply the values listed in install_requirements; missing ones answer 422 install_input_required with missing_fields. OAuth catalog MCPs return a connect link, like OAuth creates.

Endpoint reference​

GET/mcps

List MCPs

Enabled and disabled MCPs of the tenant, sorted by name. Filters: `name` (case-insensitive substring), `slug`, `enabled`, `auth_type`, `transport_type` and `source`. `tool_count` and `connection_state` are live values; they never invalidate a cursor.

REQUIRESread
Path, query & header parameters 8
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.

name (query)stringoptional

Case-insensitive substring of the MCP name.

slug (query)stringoptional

Exact slug.

enabled (query)booleanoptional

true or false.

auth_type (query)stringoptional

Authentication the MCP uses upstream.

"api_key""no_auth""oauth""oauth_passthrough"
transport_type (query)stringoptional

Exact transport type: http or sse.

source (query)stringoptional

How the MCP was added: custom, catalog (MCP Library), api (REST API) or system (provided by Quilr).

"api""catalog""custom""system"

No request body.

curl --request GET \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/mcps?limit=50' \
--header 'Authorization: Bearer <management-key>'

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

POST/mcps

Add a remote MCP

Registers a remote MCP server by URL and fetches its tools. `auth.type` selects upstream authentication; credentials are shared by all users of the tenant. OAuth MCPs are created with `connection_state` pending_connection and a single-use `connect` link that finishes the sign-in for the key owner when opened (no Quilr sign-in; share it only with the person who should connect) (oauth_passthrough MCPs need no link: each client brings its own token). `settings` (settings:write) and `enabled` apply before the MCP is returned. 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`.

REQUIRESmcps:write+ credentials:write (conditional)+ settings:write (conditional)
Path, query & header parameters 1
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

authobjectoptional

Upstream authentication. Credentials are always shared by all users of the tenant.

Object fields
client_idstringoptional

oauth_dcr / oauth_login: your OAuth client id (with client_secret). oauth_dcr with a client skips registration and is saved as oauth_login.

min length: 1max length: 8192write only
client_secretstringoptional

oauth_dcr / oauth_login: your OAuth client secret (with client_id). For a public client (no secret) send "-".

min length: 1max length: 8192write only
extra_headersmap<string, string>optional

Extra headers sent upstream on every call.

write only
Map value specification
string
max length: 8192
extra_query_paramsmap<string, string>optional

Extra query parameters sent upstream.

write only
Map value specification
string
max length: 8192
header_namestringoptional

static only: send the token in this header.

min length: 1max length: 256
query_paramstringoptional

static only: send the token in this query parameter.

min length: 1max length: 256
schemestringoptional

static only: authorization scheme (default Bearer).

max length: 64
tokenstringoptional

static only: the API key or token.

min length: 1max length: 8192write only
typestringrequired

none; static (token); oauth_dcr (dynamic client registration); oauth_login (OAuth with a registered or provider-issued client); oauth_passthrough (each MCP client brings its own OAuth token).

"none""static""oauth_dcr""oauth_login""oauth_passthrough"

Unknown fields are rejected in this object.

descriptionstring | nulloptional
max length: 8000
enabledbooleanoptional

false creates the MCP disabled.

namestringrequired
min length: 1max length: 200
remote_connector_idstringoptional

Reach a private-network server through this Remote Connector.

min length: 1max length: 128
settingsobjectoptional

Sectioned MCP settings patch. Unknown fields at any depth are refused. tools, dlp, token_saving, access_control, tool_sync, tool_exposure and onemcp merge by key into the stored settings; web_search_policy and oauth_scopes replace the stored value; oauth_scopes: null and upstream_session_max_concurrency: null clear it.

min fields: 1
Object fields
access_controlobjectoptional

Which agents, smart groups and users may use this MCP. Users are checked in this order, first match wins: denied_users (blocked), allowed_users (allowed, even when a group of theirs is denied), denied_smart_groups (blocked), then allowed_smart_groups (when not empty, users in none of them are blocked). Otherwise allowed.

Object fields
allowed_agentsarray<string>optional
Array item specification
string
allowed_smart_groupsarray<string>optional
Array item specification
string
allowed_usersarray<string>optional
Array item specification
string
denied_smart_groupsarray<string>optional
Array item specification
string
denied_usersarray<string>optional
Array item specification
string

Unknown fields are rejected in this object.

dlpobjectoptional

Data loss prevention actions and enabled risk categories for this MCP.

Object fields
data_risk_actionstringoptional
data_risk_request_actionstringoptional
data_risk_response_actionstringoptional
enabled_oob_adversarial_risk_categoriesmap<string, boolean>optional
Map value specification
boolean
enabled_oob_data_risk_categoriesmap<string, boolean>optional
Map value specification
boolean
enabled_oob_edm_sub_categoriesmap<string, boolean>optional
Map value specification
boolean
oob_adversarial_risk_category_request_actionsmap<string, string>optional
Map value specification
string
oob_adversarial_risk_category_response_actionsmap<string, string>optional
Map value specification
string
oob_data_risk_category_request_actionsmap<string, string>optional
Map value specification
string
oob_data_risk_category_response_actionsmap<string, string>optional
Map value specification
string
oob_edm_sub_category_request_actionsmap<string, string>optional
Map value specification
string
oob_edm_sub_category_response_actionsmap<string, string>optional
Map value specification
string

Unknown fields are rejected in this object.

oauth_scopesarray<string> | nulloptional
Variant 1 array<string>
array<string>

Also accepts null.

onemcpobjectoptional

How this MCP takes part in OneMCP; hidden makes it reachable only at its own endpoint.

Object fields
hiddenbooleanoptional

Unknown fields are rejected in this object.

send_user_claims_headerbooleanoptional
token_savingobjectoptional

Output transforms that reduce tokens sent to the model.

Object fields
html_to_textbooleanoptional
markdown_to_textbooleanoptional
smart_json_compressionbooleanoptional
strip_base64booleanoptional

Replaces detected base64 content with a byte-count placeholder. Removed content is unavailable to the model.

text_compressionbooleanoptional

Unknown fields are rejected in this object.

tool_exposureobjectoptional

Smart tool lists: list only the most-used tools plus a tool search, or expose a code tool. Both are off by default.

Object fields
codebooleanoptional
pinnedarray<string>optional
Array item specification
string
top_toolsbooleanoptional

Unknown fields are rejected in this object.

tool_syncobjectoptional

What happens when the upstream tool list changes: notify (record the change for review), auto (refresh the tool list) or off.

Object fields
modestringoptional
"notify""auto""off"
new_toolsstringoptional
"inherit""hold""allow"

Unknown fields are rejected in this object.

toolsmap<string, object>optional
Map value specification
enabledbooleanoptional
enforce_confirmationbooleanoptional
require_justificationbooleanoptional

Unknown fields are rejected in this object.

upstream_session_max_concurrencyinteger | nulloptional
Variant 1 integer
integer
min: 1max: 256

Also accepts null.

web_search_policyobjectoptional

Web search policy of the Quilr web search MCP: per smart group domain exclusions and URL category overrides.

Object fields
group_excluded_domainsmap<string, array<string>>optional
Map value specification
array<string>
zia_check_timeout_secondsnumberoptional
min: 1max: 30
zia_url_overridesarray<object>optional
Array item specification
actionstringrequired
"allow""block"
domain_patternsarray<string>optional
Array item specification
string
scope_namestringoptional
scope_namesarray<string>optional
Array item specification
string
scope_typestringrequired
"global""zia_group""zia_department"

Unknown fields are rejected in this object.

Unknown fields are rejected in this object.

Unknown fields are rejected in this object.

slugstringoptional

URL slug of the MCP endpoint; default derived from the name.

min length: 1max length: 128
transportstringrequired

The upstream MCP server URL (Streamable HTTP or SSE).

max length: 4096format: uri

Unknown fields are rejected in this object.

curl --request POST \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/mcps' \
--header 'Authorization: Bearer <management-key>' \
--header 'Idempotency-Key: create-files-mcp-2026-11-14' \
--header 'Content-Type: application/json' \
--data '{
"auth": {
"type": "oauth_dcr"
},
"name": "Tracker",
"transport": "https://tracker.example.com/mcp"
}'

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

POST/mcps/api

Add a REST API as an MCP

Exposes a REST API as MCP tools: one tool per selected OpenAPI operation (`openapi`), or a generic request tool restricted by `access` rules. Preview the spec first with POST /mcps/api:preview and pass its `preview_token`. Spec errors use the same codes on create, preview, configuration changes and resync: 400 `spec_missing`, `spec_invalid`, `unsupported_encoding`, `blocked_destination` (the URL points somewhere the gateway does not call), `invalid_operation_override` (with `unknown_operations`), `no_operations_selected`; 410 `preview_expired` (preview again); 413 `spec_too_large`; 422 `tools_too_large`; 502 `fetch_failed` (the document could not be downloaded). Requests are limited to 1 MiB, so an inline document (`spec_text` or `spec_base64`) over about 750 KB must be sent as `source_url` instead. 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`.

REQUIRESmcps:write+ credentials:write (conditional)+ settings:write (conditional)
Path, query & header parameters 1
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

A REST API exposed as MCP tools. With `openapi`, tools come from the OpenAPI operations; without it, one generic request tool is exposed.

accessobjectoptional

Deny wins; a nonempty allow list must match; no rules allows everything.

Object fields
allowarray<object>optional
max items: 64
Array item specification
keywordsarray<string>optional
max items: 32
Array item specification
string
methodsarray<string>optional

HTTP methods, for example GET.

Array item specification
string
pathstringoptional

Path glob, for example /invoices/*.

tagsarray<string>optional

OpenAPI tags.

Array item specification
string

Unknown fields are rejected in this object.

denyarray<object>optional
max items: 64
Array item specification
keywordsarray<string>optional
max items: 32
Array item specification
string
methodsarray<string>optional

HTTP methods, for example GET.

Array item specification
string
pathstringoptional

Path glob, for example /invoices/*.

tagsarray<string>optional

OpenAPI tags.

Array item specification
string

Unknown fields are rejected in this object.

Unknown fields are rejected in this object.

auth_tokenstringoptional

Static API key or token sent upstream.

min length: 1max length: 8192write only
base_urlstringrequired

Base URL requests are sent to.

max length: 2048format: uri
descriptionstring | nulloptional
max length: 8000
docs_textstring | nulloptional

Free-form API documentation for generic mode.

max length: 1048576
enabledbooleanoptional
max_response_bytesinteger | nulloptional
namestringrequired
min length: 1max length: 256
openapiobject | nulloptional
ApiOpenApiSelection object
enable_generic_fallbackbooleanoptional

Also expose a generic request tool.

default: false
overridesmap<string, object>optional
Map value specification
descriptionstringoptional
max length: 8000
enabledboolean | nulloptional

Force the operation on or off; null lets the access rules decide.

fixed_paramsobjectoptional

Parameter values always sent upstream (hidden from the model). Nonempty values need credentials:write.

namestringoptional

Tool name to publish.

max length: 128

Unknown fields are rejected in this object.

preview_tokenstringoptional

Token from POST /mcps/api:preview (preferred: no re-fetch).

max length: 128
source_urlstringoptional

URL of the OpenAPI document, fetched now.

max length: 4096format: uri
spec_base64stringoptional

OpenAPI document, base64 encoded.

spec_textstringoptional

OpenAPI document as JSON or YAML text.

Unknown fields are rejected in this object.

Also accepts null.

remote_connector_idstring | nulloptional
max length: 128
settingsobjectoptional

Sectioned MCP settings patch. Unknown fields at any depth are refused. tools, dlp, token_saving, access_control, tool_sync, tool_exposure and onemcp merge by key into the stored settings; web_search_policy and oauth_scopes replace the stored value; oauth_scopes: null and upstream_session_max_concurrency: null clear it.

min fields: 1
Object fields
access_controlobjectoptional

Which agents, smart groups and users may use this MCP. Users are checked in this order, first match wins: denied_users (blocked), allowed_users (allowed, even when a group of theirs is denied), denied_smart_groups (blocked), then allowed_smart_groups (when not empty, users in none of them are blocked). Otherwise allowed.

Object fields
allowed_agentsarray<string>optional
Array item specification
string
allowed_smart_groupsarray<string>optional
Array item specification
string
allowed_usersarray<string>optional
Array item specification
string
denied_smart_groupsarray<string>optional
Array item specification
string
denied_usersarray<string>optional
Array item specification
string

Unknown fields are rejected in this object.

dlpobjectoptional

Data loss prevention actions and enabled risk categories for this MCP.

Object fields
data_risk_actionstringoptional
data_risk_request_actionstringoptional
data_risk_response_actionstringoptional
enabled_oob_adversarial_risk_categoriesmap<string, boolean>optional
Map value specification
boolean
enabled_oob_data_risk_categoriesmap<string, boolean>optional
Map value specification
boolean
enabled_oob_edm_sub_categoriesmap<string, boolean>optional
Map value specification
boolean
oob_adversarial_risk_category_request_actionsmap<string, string>optional
Map value specification
string
oob_adversarial_risk_category_response_actionsmap<string, string>optional
Map value specification
string
oob_data_risk_category_request_actionsmap<string, string>optional
Map value specification
string
oob_data_risk_category_response_actionsmap<string, string>optional
Map value specification
string
oob_edm_sub_category_request_actionsmap<string, string>optional
Map value specification
string
oob_edm_sub_category_response_actionsmap<string, string>optional
Map value specification
string

Unknown fields are rejected in this object.

oauth_scopesarray<string> | nulloptional
Variant 1 array<string>
array<string>

Also accepts null.

onemcpobjectoptional

How this MCP takes part in OneMCP; hidden makes it reachable only at its own endpoint.

Object fields
hiddenbooleanoptional

Unknown fields are rejected in this object.

send_user_claims_headerbooleanoptional
token_savingobjectoptional

Output transforms that reduce tokens sent to the model.

Object fields
html_to_textbooleanoptional
markdown_to_textbooleanoptional
smart_json_compressionbooleanoptional
strip_base64booleanoptional

Replaces detected base64 content with a byte-count placeholder. Removed content is unavailable to the model.

text_compressionbooleanoptional

Unknown fields are rejected in this object.

tool_exposureobjectoptional

Smart tool lists: list only the most-used tools plus a tool search, or expose a code tool. Both are off by default.

Object fields
codebooleanoptional
pinnedarray<string>optional
Array item specification
string
top_toolsbooleanoptional

Unknown fields are rejected in this object.

tool_syncobjectoptional

What happens when the upstream tool list changes: notify (record the change for review), auto (refresh the tool list) or off.

Object fields
modestringoptional
"notify""auto""off"
new_toolsstringoptional
"inherit""hold""allow"

Unknown fields are rejected in this object.

toolsmap<string, object>optional
Map value specification
enabledbooleanoptional
enforce_confirmationbooleanoptional
require_justificationbooleanoptional

Unknown fields are rejected in this object.

upstream_session_max_concurrencyinteger | nulloptional
Variant 1 integer
integer
min: 1max: 256

Also accepts null.

web_search_policyobjectoptional

Web search policy of the Quilr web search MCP: per smart group domain exclusions and URL category overrides.

Object fields
group_excluded_domainsmap<string, array<string>>optional
Map value specification
array<string>
zia_check_timeout_secondsnumberoptional
min: 1max: 30
zia_url_overridesarray<object>optional
Array item specification
actionstringrequired
"allow""block"
domain_patternsarray<string>optional
Array item specification
string
scope_namestringoptional
scope_namesarray<string>optional
Array item specification
string
scope_typestringrequired
"global""zia_group""zia_department"

Unknown fields are rejected in this object.

Unknown fields are rejected in this object.

Unknown fields are rejected in this object.

slugstringoptional
max length: 128
timeout_snumber | nulloptional

Upstream request timeout, seconds.

upstream_auth_extra_headersmap<string, string>optional

Extra headers sent upstream on every call.

write only
Map value specification
string
max length: 8192
upstream_auth_extra_query_paramsmap<string, string>optional

Extra query parameters sent upstream.

write only
Map value specification
string
max length: 8192
upstream_auth_header_namestringoptional
max length: 128
upstream_auth_modestringoptional

Credentials set through this API are always shared by all users of the tenant.

"admin_shared"
upstream_auth_query_paramstringoptional
max length: 128
upstream_auth_schemestringoptional

Authorization scheme for bearer (default Bearer).

max length: 128
upstream_auth_typestringoptional

How the token is sent: bearer (default), header or query.

"bearer""header""query"

Unknown fields are rejected in this object.

curl --request POST \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/mcps/api' \
--header 'Authorization: Bearer <management-key>' \
--header 'Idempotency-Key: create-files-mcp-2026-11-14' \
--header 'Content-Type: application/json' \
--data '{
"auth_token": "<token>",
"base_url": "https://billing.example.com/v1",
"name": "Billing API",
"openapi": {
"preview_token": "<preview-token>"
},
"upstream_auth_type": "bearer"
}'

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

POST/mcps/api:preview

Preview a REST API spec

Fetches or parses an OpenAPI document without saving anything and lists its operations with the selection the given `access` rules and `overrides` produce. Returns a `preview_token` (reuse it to reselect or to create without re-fetching). Spec errors use the same codes on create, preview, configuration changes and resync: 400 `spec_missing`, `spec_invalid`, `unsupported_encoding`, `blocked_destination` (the URL points somewhere the gateway does not call), `invalid_operation_override` (with `unknown_operations`), `no_operations_selected`; 410 `preview_expired` (preview again); 413 `spec_too_large`; 422 `tools_too_large`; 502 `fetch_failed` (the document could not be downloaded). Requests are limited to 1 MiB, so an inline document (`spec_text` or `spec_base64`) over about 750 KB must be sent as `source_url` instead.

REQUIRESmcps:write+ credentials:write (conditional)
Full request body specification application/json

Send one spec source: preview_token, source_url, spec_text or spec_base64.

accessobjectoptional

Deny wins; a nonempty allow list must match; no rules allows everything.

Object fields
allowarray<object>optional
max items: 64
Array item specification
keywordsarray<string>optional
max items: 32
Array item specification
string
methodsarray<string>optional

HTTP methods, for example GET.

Array item specification
string
pathstringoptional

Path glob, for example /invoices/*.

tagsarray<string>optional

OpenAPI tags.

Array item specification
string

Unknown fields are rejected in this object.

denyarray<object>optional
max items: 64
Array item specification
keywordsarray<string>optional
max items: 32
Array item specification
string
methodsarray<string>optional

HTTP methods, for example GET.

Array item specification
string
pathstringoptional

Path glob, for example /invoices/*.

tagsarray<string>optional

OpenAPI tags.

Array item specification
string

Unknown fields are rejected in this object.

Unknown fields are rejected in this object.

fetch_headersmap<string, string>optional

Headers for downloading a protected spec; used once, never stored.

write only
Map value specification
string
max length: 8192
overridesmap<string, object>optional
Map value specification
descriptionstringoptional
max length: 8000
enabledboolean | nulloptional

Force the operation on or off; null lets the access rules decide.

fixed_paramsobjectoptional

Parameter values always sent upstream (hidden from the model). Nonempty values need credentials:write.

namestringoptional

Tool name to publish.

max length: 128

Unknown fields are rejected in this object.

preview_tokenstringoptional

Token from POST /mcps/api:preview (preferred: no re-fetch).

max length: 128
remote_connector_idstringoptional
max length: 128
source_urlstringoptional

URL of the OpenAPI document, fetched now.

max length: 4096format: uri
spec_base64stringoptional

OpenAPI document, base64 encoded.

spec_textstringoptional

OpenAPI document as JSON or YAML text.

Unknown fields are rejected in this object.

curl --request POST \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/mcps/api:preview' \
--header 'Authorization: Bearer <management-key>' \
--header 'Content-Type: application/json' \
--data '{
"source_url": "https://billing.example.com/openapi.json"
}'

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

DELETE/mcps/{mcp_id}

Remove an MCP

Removes a custom or REST API MCP, or uninstalls a catalog MCP, together with its stored credentials and settings. MCPs provided by Quilr cannot be removed (403 `system_mcp`; disable them instead). An MCP referenced by the active QuilrQL policy answers 409 `policy_dependency`. Send the quoted `version` from the latest read in If-Match (428 when missing, 412 when stale).

REQUIRESmcps: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 DELETE \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/mcps/a1b2c3d4' \
--header 'Authorization: Bearer <management-key>' \
--header 'If-Match: "r4"'

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

GET/mcps/{mcp_id}

Read an MCP

One MCP with its last tool-fetch errors (fixed codes, never upstream text). `version` is the ETag of the MCP configuration, shared by settings, overrides and upstream credentials. MCPs of other tenants answer 404.

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

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

PATCH/mcps/{mcp_id}

Rename, describe, enable or disable an MCP

Changes `name`, `description` and/or `enabled`. Disabling stops serving the MCP to every client until it is enabled again. Send the quoted `version` from the latest read in If-Match (428 when missing, 412 when stale).

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

descriptionstring | nulloptional

null or an empty string clears it.

max length: 2000
enabledbooleanoptional

false stops serving the MCP to every client.

namestringoptional
min length: 1max length: 200

Unknown fields are rejected in this object.

curl --request PATCH \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/mcps/a1b2c3d4' \
--header 'Authorization: Bearer <management-key>' \
--header 'If-Match: "r4"' \
--header 'Content-Type: application/json' \
--data '{
"enabled": false
}'

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

GET/mcps/{mcp_id}/tools

List an MCP's tools

Cached tools, resources and prompts of the MCP. Each tool carries its enabled and confirmation settings, its review state (held or rejected tools are listed too) and its all-time call count (null with a `usage_unavailable` warning when usage data cannot be read).

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

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

POST/mcps:probe

Check an MCP URL

Connects to a URL without saving anything and reports the transport, OAuth discovery results and whether a credential is required, to choose `auth.type` before creating.

REQUIRESmcps:write+ credentials:write (conditional)
Full request body specification application/json

extra_headersmap<string, string>optional
write only
Map value specification
string
max length: 8192
extra_query_paramsmap<string, string>optional
write only
Map value specification
string
max length: 8192
remote_connector_idstringoptional
min length: 1max length: 128
transportstringrequired

The upstream MCP server URL to check.

max length: 4096format: uri

Unknown fields are rejected in this object.

curl --request POST \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/mcps:probe' \
--header 'Authorization: Bearer <management-key>' \
--header 'Content-Type: application/json' \
--data '{
"transport": "https://tracker.example.com/mcp"
}'

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

GET/catalog

List the MCP Library

Catalog MCPs with this tenant's install state. Filters: `query` (search), `install_status` and `auth_type`. `install_requirements` lists the values an install needs.

REQUIRESread
Path, query & header parameters 5
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.

query (query)stringoptional

Search text matched against catalog names and descriptions (at most 256 characters).

install_status (query)stringoptional

installed or not_installed for your tenant.

"installed""not_installed"
auth_type (query)stringoptional

Catalog authentication kind.

"oauth""api_key""passthrough""oauth_passthrough""no_auth""none"

No request body.

curl --request GET \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/catalog?limit=50' \
--header 'Authorization: Bearer <management-key>'

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

GET/catalog/{catalog_id}

Read a catalog entry

One catalog MCP with its install requirements and this tenant's install state.

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

Catalog entry id from `GET /catalog`.

No request body.

curl --request GET \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/catalog/github' \
--header 'Authorization: Bearer <management-key>'

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

POST/catalog/{catalog_id}/install

Install a catalog MCP

Installs a catalog MCP for the tenant (once per tenant: 409 `already_installed`). Supply the values listed in `install_requirements`; missing ones answer 422 `install_input_required` with `missing_fields`. OAuth catalog MCPs return a `connect` link. 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`.

REQUIRESmcps:write+ credentials:write (conditional)
Path, query & header parameters 2
catalog_id (path)stringrequired

Catalog entry id from `GET /catalog`.

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

Install inputs. `GET /catalog/{catalog_id}` lists `install_requirements`; missing required values answer 422 `install_input_required` with `missing_fields`.

auth_tokenstringoptional

Static API key or token sent upstream.

min length: 1max length: 8192write only
oauth_callback_modestringoptional
max length: 128
oauth_client_idstringoptional

Your OAuth client id, for catalog MCPs that need one.

min length: 1max length: 8192write only
oauth_client_secretstringoptional

Your OAuth client secret; "-" for a public client (no secret).

min length: 1max length: 8192write only
transport_valuesmap<string, string>optional

Values for placeholders in the catalog URL template.

write only
Map value specification
string
max length: 8192
upstream_auth_extra_headersmap<string, string>optional

Extra headers sent upstream on every call.

write only
Map value specification
string
max length: 8192
upstream_auth_extra_query_paramsmap<string, string>optional

Extra query parameters sent upstream.

write only
Map value specification
string
max length: 8192
upstream_auth_header_namestringoptional
max length: 128
upstream_auth_modestringoptional

Credentials set through this API are always shared by all users of the tenant.

"admin_shared"
upstream_auth_query_paramstringoptional
max length: 128
upstream_auth_schemestringoptional

Authorization scheme for bearer (default Bearer).

max length: 128
upstream_auth_typestringoptional

How the token is sent: bearer (default), header or query.

"bearer""header""query"

Unknown fields are rejected in this object.

curl --request POST \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/catalog/github/install' \
--header 'Authorization: Bearer <management-key>' \
--header 'Idempotency-Key: create-files-mcp-2026-11-14' \
--header 'Content-Type: application/json' \
--data '{}'

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