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:
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).
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:
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:
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
/mcpsList 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.
readPath, query & header parameters 8
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.
name (query)stringoptionalCase-insensitive substring of the MCP name.
slug (query)stringoptionalExact slug.
enabled (query)booleanoptionaltrue or false.
auth_type (query)stringoptionalAuthentication the MCP uses upstream.
"api_key""no_auth""oauth""oauth_passthrough"transport_type (query)stringoptionalExact transport type: http or sse.
source (query)stringoptionalHow 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
/mcpsAdd 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`.
mcps:write+ credentials:write (conditional)+ settings:write (conditional)Path, query & header parameters 1
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
authobjectoptionalUpstream authentication. Credentials are always shared by all users of the tenant.
Object fields
client_idstringoptionaloauth_dcr / oauth_login: your OAuth client id (with client_secret). oauth_dcr with a client skips registration and is saved as oauth_login.
client_secretstringoptionaloauth_dcr / oauth_login: your OAuth client secret (with client_id). For a public client (no secret) send "-".
extra_headersmap<string, string>optionalExtra headers sent upstream on every call.
Map value specification
stringextra_query_paramsmap<string, string>optionalExtra query parameters sent upstream.
Map value specification
stringheader_namestringoptionalstatic only: send the token in this header.
query_paramstringoptionalstatic only: send the token in this query parameter.
schemestringoptionalstatic only: authorization scheme (default Bearer).
tokenstringoptionalstatic only: the API key or token.
typestringrequirednone; 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 | nulloptionalenabledbooleanoptionalfalse creates the MCP disabled.
namestringrequiredremote_connector_idstringoptionalReach a private-network server through this Remote Connector.
settingsobjectoptionalSectioned 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.
Object fields
access_controlobjectoptionalWhich 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>optionalArray item specification
stringallowed_smart_groupsarray<string>optionalArray item specification
stringallowed_usersarray<string>optionalArray item specification
stringdenied_smart_groupsarray<string>optionalArray item specification
stringdenied_usersarray<string>optionalArray item specification
stringUnknown fields are rejected in this object.
dlpobjectoptionalData loss prevention actions and enabled risk categories for this MCP.
Object fields
data_risk_actionstringoptionaldata_risk_request_actionstringoptionaldata_risk_response_actionstringoptionalenabled_oob_adversarial_risk_categoriesmap<string, boolean>optionalMap value specification
booleanenabled_oob_data_risk_categoriesmap<string, boolean>optionalMap value specification
booleanenabled_oob_edm_sub_categoriesmap<string, boolean>optionalMap value specification
booleanoob_adversarial_risk_category_request_actionsmap<string, string>optionalMap value specification
stringoob_adversarial_risk_category_response_actionsmap<string, string>optionalMap value specification
stringoob_data_risk_category_request_actionsmap<string, string>optionalMap value specification
stringoob_data_risk_category_response_actionsmap<string, string>optionalMap value specification
stringoob_edm_sub_category_request_actionsmap<string, string>optionalMap value specification
stringoob_edm_sub_category_response_actionsmap<string, string>optionalMap value specification
stringUnknown fields are rejected in this object.
oauth_scopesarray<string> | nulloptionalVariant 1 array<string>
array<string>Also accepts null.
onemcpobjectoptionalHow this MCP takes part in OneMCP; hidden makes it reachable only at its own endpoint.
Object fields
hiddenbooleanoptionalUnknown fields are rejected in this object.
send_user_claims_headerbooleanoptionaltoken_savingobjectoptionalOutput transforms that reduce tokens sent to the model.
Object fields
html_to_textbooleanoptionalmarkdown_to_textbooleanoptionalsmart_json_compressionbooleanoptionalstrip_base64booleanoptionalReplaces detected base64 content with a byte-count placeholder. Removed content is unavailable to the model.
text_compressionbooleanoptionalUnknown fields are rejected in this object.
tool_exposureobjectoptionalSmart tool lists: list only the most-used tools plus a tool search, or expose a code tool. Both are off by default.
Object fields
codebooleanoptionalpinnedarray<string>optionalArray item specification
stringtop_toolsbooleanoptionalUnknown fields are rejected in this object.
tool_syncobjectoptionalWhat 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>optionalMap value specification
enabledbooleanoptionalenforce_confirmationbooleanoptionalrequire_justificationbooleanoptionalUnknown fields are rejected in this object.
upstream_session_max_concurrencyinteger | nulloptionalVariant 1 integer
integerAlso accepts null.
web_search_policyobjectoptionalWeb 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>>optionalMap value specification
array<string>zia_check_timeout_secondsnumberoptionalzia_url_overridesarray<object>optionalArray item specification
actionstringrequired"allow""block"domain_patternsarray<string>optionalArray item specification
stringscope_namestringoptionalscope_namesarray<string>optionalArray item specification
stringscope_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.
slugstringoptionalURL slug of the MCP endpoint; default derived from the name.
transportstringrequiredThe upstream MCP server URL (Streamable HTTP or SSE).
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
/mcps/apiAdd 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`.
mcps:write+ credentials:write (conditional)+ settings:write (conditional)Path, query & header parameters 1
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
A REST API exposed as MCP tools. With `openapi`, tools come from the OpenAPI operations; without it, one generic request tool is exposed.
accessobjectoptionalDeny wins; a nonempty allow list must match; no rules allows everything.
Object fields
allowarray<object>optionalArray item specification
keywordsarray<string>optionalArray item specification
stringmethodsarray<string>optionalHTTP methods, for example GET.
Array item specification
stringpathstringoptionalPath glob, for example /invoices/*.
tagsarray<string>optionalOpenAPI tags.
Array item specification
stringUnknown fields are rejected in this object.
denyarray<object>optionalArray item specification
keywordsarray<string>optionalArray item specification
stringmethodsarray<string>optionalHTTP methods, for example GET.
Array item specification
stringpathstringoptionalPath glob, for example /invoices/*.
tagsarray<string>optionalOpenAPI tags.
Array item specification
stringUnknown fields are rejected in this object.
Unknown fields are rejected in this object.
auth_tokenstringoptionalStatic API key or token sent upstream.
base_urlstringrequiredBase URL requests are sent to.
descriptionstring | nulloptionaldocs_textstring | nulloptionalFree-form API documentation for generic mode.
enabledbooleanoptionalmax_response_bytesinteger | nulloptionalnamestringrequiredopenapiobject | nulloptionalApiOpenApiSelection object
enable_generic_fallbackbooleanoptionalAlso expose a generic request tool.
overridesmap<string, object>optionalMap value specification
descriptionstringoptionalenabledboolean | nulloptionalForce the operation on or off; null lets the access rules decide.
fixed_paramsobjectoptionalParameter values always sent upstream (hidden from the model). Nonempty values need credentials:write.
namestringoptionalTool name to publish.
Unknown fields are rejected in this object.
preview_tokenstringoptionalToken from POST /mcps/api:preview (preferred: no re-fetch).
source_urlstringoptionalURL of the OpenAPI document, fetched now.
spec_base64stringoptionalOpenAPI document, base64 encoded.
spec_textstringoptionalOpenAPI document as JSON or YAML text.
Unknown fields are rejected in this object.
Also accepts null.
remote_connector_idstring | nulloptionalsettingsobjectoptionalSectioned 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.
Object fields
access_controlobjectoptionalWhich 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>optionalArray item specification
stringallowed_smart_groupsarray<string>optionalArray item specification
stringallowed_usersarray<string>optionalArray item specification
stringdenied_smart_groupsarray<string>optionalArray item specification
stringdenied_usersarray<string>optionalArray item specification
stringUnknown fields are rejected in this object.
dlpobjectoptionalData loss prevention actions and enabled risk categories for this MCP.
Object fields
data_risk_actionstringoptionaldata_risk_request_actionstringoptionaldata_risk_response_actionstringoptionalenabled_oob_adversarial_risk_categoriesmap<string, boolean>optionalMap value specification
booleanenabled_oob_data_risk_categoriesmap<string, boolean>optionalMap value specification
booleanenabled_oob_edm_sub_categoriesmap<string, boolean>optionalMap value specification
booleanoob_adversarial_risk_category_request_actionsmap<string, string>optionalMap value specification
stringoob_adversarial_risk_category_response_actionsmap<string, string>optionalMap value specification
stringoob_data_risk_category_request_actionsmap<string, string>optionalMap value specification
stringoob_data_risk_category_response_actionsmap<string, string>optionalMap value specification
stringoob_edm_sub_category_request_actionsmap<string, string>optionalMap value specification
stringoob_edm_sub_category_response_actionsmap<string, string>optionalMap value specification
stringUnknown fields are rejected in this object.
oauth_scopesarray<string> | nulloptionalVariant 1 array<string>
array<string>Also accepts null.
onemcpobjectoptionalHow this MCP takes part in OneMCP; hidden makes it reachable only at its own endpoint.
Object fields
hiddenbooleanoptionalUnknown fields are rejected in this object.
send_user_claims_headerbooleanoptionaltoken_savingobjectoptionalOutput transforms that reduce tokens sent to the model.
Object fields
html_to_textbooleanoptionalmarkdown_to_textbooleanoptionalsmart_json_compressionbooleanoptionalstrip_base64booleanoptionalReplaces detected base64 content with a byte-count placeholder. Removed content is unavailable to the model.
text_compressionbooleanoptionalUnknown fields are rejected in this object.
tool_exposureobjectoptionalSmart tool lists: list only the most-used tools plus a tool search, or expose a code tool. Both are off by default.
Object fields
codebooleanoptionalpinnedarray<string>optionalArray item specification
stringtop_toolsbooleanoptionalUnknown fields are rejected in this object.
tool_syncobjectoptionalWhat 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>optionalMap value specification
enabledbooleanoptionalenforce_confirmationbooleanoptionalrequire_justificationbooleanoptionalUnknown fields are rejected in this object.
upstream_session_max_concurrencyinteger | nulloptionalVariant 1 integer
integerAlso accepts null.
web_search_policyobjectoptionalWeb 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>>optionalMap value specification
array<string>zia_check_timeout_secondsnumberoptionalzia_url_overridesarray<object>optionalArray item specification
actionstringrequired"allow""block"domain_patternsarray<string>optionalArray item specification
stringscope_namestringoptionalscope_namesarray<string>optionalArray item specification
stringscope_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.
slugstringoptionaltimeout_snumber | nulloptionalUpstream request timeout, seconds.
upstream_auth_extra_headersmap<string, string>optionalExtra headers sent upstream on every call.
Map value specification
stringupstream_auth_extra_query_paramsmap<string, string>optionalExtra query parameters sent upstream.
Map value specification
stringupstream_auth_header_namestringoptionalupstream_auth_modestringoptionalCredentials set through this API are always shared by all users of the tenant.
"admin_shared"upstream_auth_query_paramstringoptionalupstream_auth_schemestringoptionalAuthorization scheme for bearer (default Bearer).
upstream_auth_typestringoptionalHow 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
/mcps/api:previewPreview 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.
mcps:write+ credentials:write (conditional)Full request body specification application/json
Send one spec source: preview_token, source_url, spec_text or spec_base64.
accessobjectoptionalDeny wins; a nonempty allow list must match; no rules allows everything.
Object fields
allowarray<object>optionalArray item specification
keywordsarray<string>optionalArray item specification
stringmethodsarray<string>optionalHTTP methods, for example GET.
Array item specification
stringpathstringoptionalPath glob, for example /invoices/*.
tagsarray<string>optionalOpenAPI tags.
Array item specification
stringUnknown fields are rejected in this object.
denyarray<object>optionalArray item specification
keywordsarray<string>optionalArray item specification
stringmethodsarray<string>optionalHTTP methods, for example GET.
Array item specification
stringpathstringoptionalPath glob, for example /invoices/*.
tagsarray<string>optionalOpenAPI tags.
Array item specification
stringUnknown fields are rejected in this object.
Unknown fields are rejected in this object.
fetch_headersmap<string, string>optionalHeaders for downloading a protected spec; used once, never stored.
Map value specification
stringoverridesmap<string, object>optionalMap value specification
descriptionstringoptionalenabledboolean | nulloptionalForce the operation on or off; null lets the access rules decide.
fixed_paramsobjectoptionalParameter values always sent upstream (hidden from the model). Nonempty values need credentials:write.
namestringoptionalTool name to publish.
Unknown fields are rejected in this object.
preview_tokenstringoptionalToken from POST /mcps/api:preview (preferred: no re-fetch).
remote_connector_idstringoptionalsource_urlstringoptionalURL of the OpenAPI document, fetched now.
spec_base64stringoptionalOpenAPI document, base64 encoded.
spec_textstringoptionalOpenAPI 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
/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).
mcps:writePath, query & header parameters 2
mcp_id (path)stringrequiredMCP id (the `id` of an MCP, not its slug).
If-Match (header)stringrequiredQuoted `version` (ETag) from the latest read of this resource.
Full request body specification application/json
No body, or an empty JSON object.
Unknown fields are rejected in this object.
curl --request 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
/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.
readPath, query & header parameters 1
mcp_id (path)stringrequiredMCP id (the `id` of an MCP, not its slug).
No request body.
curl --request GET \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/mcps/a1b2c3d4' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Scopes Try it in the playground
/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).
mcps:writePath, query & header parameters 2
mcp_id (path)stringrequiredMCP id (the `id` of an MCP, not its slug).
If-Match (header)stringrequiredQuoted `version` (ETag) from the latest read of this resource.
Full request body specification application/json
descriptionstring | nulloptionalnull or an empty string clears it.
enabledbooleanoptionalfalse stops serving the MCP to every client.
namestringoptionalUnknown 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
/mcps/{mcp_id}/toolsList 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).
readPath, query & header parameters 1
mcp_id (path)stringrequiredMCP id (the `id` of an MCP, not its slug).
No request body.
curl --request GET \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/mcps/a1b2c3d4/tools' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Scopes Try it in the playground
/mcps:probeCheck 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.
mcps:write+ credentials:write (conditional)Full request body specification application/json
extra_headersmap<string, string>optionalMap value specification
stringextra_query_paramsmap<string, string>optionalMap value specification
stringremote_connector_idstringoptionaltransportstringrequiredThe upstream MCP server URL to check.
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
/catalogList 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.
readPath, query & header parameters 5
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.
query (query)stringoptionalSearch text matched against catalog names and descriptions (at most 256 characters).
install_status (query)stringoptionalinstalled or not_installed for your tenant.
"installed""not_installed"auth_type (query)stringoptionalCatalog 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
/catalog/{catalog_id}Read a catalog entry
One catalog MCP with its install requirements and this tenant's install state.
readPath, query & header parameters 1
catalog_id (path)stringrequiredCatalog 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
/catalog/{catalog_id}/installInstall 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`.
mcps:write+ credentials:write (conditional)Path, query & header parameters 2
catalog_id (path)stringrequiredCatalog entry id from `GET /catalog`.
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
Install inputs. `GET /catalog/{catalog_id}` lists `install_requirements`; missing required values answer 422 `install_input_required` with `missing_fields`.
auth_tokenstringoptionalStatic API key or token sent upstream.
oauth_callback_modestringoptionaloauth_client_idstringoptionalYour OAuth client id, for catalog MCPs that need one.
oauth_client_secretstringoptionalYour OAuth client secret; "-" for a public client (no secret).
transport_valuesmap<string, string>optionalValues for placeholders in the catalog URL template.
Map value specification
stringupstream_auth_extra_headersmap<string, string>optionalExtra headers sent upstream on every call.
Map value specification
stringupstream_auth_extra_query_paramsmap<string, string>optionalExtra query parameters sent upstream.
Map value specification
stringupstream_auth_header_namestringoptionalupstream_auth_modestringoptionalCredentials set through this API are always shared by all users of the tenant.
"admin_shared"upstream_auth_query_paramstringoptionalupstream_auth_schemestringoptionalAuthorization scheme for bearer (default Bearer).
upstream_auth_typestringoptionalHow 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