REST API MCPs API
A REST API MCP exposes a REST API as MCP tools (see API to MCP). You add one with POST /mcps/api; these operations change it afterwards. They answer 409 not_api_mcp for other MCPs. Try them in the MCP Management API playground.
Read the configuration
GET /mcps/{mcp_id}/api-config returns the base URL, timeout, response size limit, access rules, the OpenAPI selection (per-operation overrides and whether the generic request tool is also exposed) and the tools it produces. Add include_operations=true to list every operation in the OpenAPI document with whether it is selected and why.
Values that can hold secrets are never returned. URLs keep their origin and path, with base_url_has_credentials / source_url_has_credentials set when the stored URL carries a query string or user info. Overrides list fixed_param_names, never the fixed values. The response version is the If-Match value for the changes below.
Change the configuration
PATCH /mcps/{mcp_id}/api-config changes only the fields you send; everything else keeps its saved value, including the secret values the read never returns. It needs mcps:write and If-Match (see versions and If-Match).
A new document follows the same rules as on create: give one over about 750 KB as source_url, because an inline document must fit in the 1 MiB request body once encoded. Document problems answer with the same codes as on create and resync (400 spec_invalid, 400 blocked_destination, 410 preview_expired, 413 spec_too_large, 422 tools_too_large, 502 fetch_failed; see REST API MCP document errors).
The response includes tool_diff with the tools added, removed and changed. A change that would expose no operation is refused with 400 no_operations_selected; overrides naming operations that are not in the document with 400 invalid_operation_override (unknown_operations). Sending base_url or remote_connector_id also needs credentials:write, even with an unchanged value, because the saved credentials, extra headers and fixed values are sent to that destination; so do nonempty fixed_params (see conditional scopes). Operation keys are case-insensitive in the method (get /pets is GET /pets). Upstream credentials and extra headers are changed with upstream credentials, not here.
Preview and test
These calls write nothing and need only read.
POST /mcps/{mcp_id}/api-config/selection-previewwith candidateaccessandoverrides(applied like the PATCH would) lists every operation with whether it would be selected.POST /mcps/{mcp_id}/api-config/access-testwith{"method", "path"}reports whether the saved rules allow that request, which rule decided, and the operation the path maps to.POST /api-access/testevaluates rules you have not saved (accessin the body) against one request.GET /api-access/presetsreturns named starting points such asread_onlyandno_deletes.
Resync the OpenAPI document
POST /mcps/{mcp_id}/api-config/resync downloads the document again from its source URL and reports operations added and removed upstream. With apply=true (and If-Match) it saves the new document: overrides of operations that still exist are kept, and new operations are saved turned off until you enable them with a PATCH. Send fetch_headers (with credentials:write) when the document needs authentication; they are used once and never stored. An uploaded document answers 409 spec_uploaded: send a new one with PATCH instead. If the new document would leave no operation selected, apply=true answers 409 no_operations_selected and saves nothing. A download that fails answers 502 fetch_failed, and a document that cannot be read 400 spec_invalid, as on create.
Endpoint reference
/api-access/presetsList access rule presets
Named starting points for access rules, such as read only.
readNo request body.
curl --request GET \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/api-access/presets' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Scopes Try it in the playground
/api-access/testTest candidate access rules
Evaluates rules you have not saved against one request.
readFull request body specification application/json
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.
methodstringrequiredHTTP method.
pathstringrequiredRequest path, for example /invoices/42.
tagsarray<string>optionalOpenAPI tags to test with; by default the matching operation's tags.
Array item specification
stringUnknown fields are rejected in this object.
curl --request POST \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/api-access/test' \
--header 'Authorization: Bearer <management-key>' \
--header 'Content-Type: application/json' \
--data '{
"access": {
"deny": [
{
"methods": [
"DELETE"
]
}
]
},
"method": "DELETE",
"path": "/pets/1"
}'
Authentication, errors & retry rules Scopes Try it in the playground
/mcps/{mcp_id}/api-configRead a REST API MCP's configuration
Base URL, limits, access rules and OpenAPI selection of an MCP created with POST /mcps/api. URLs keep origin and path; fixed parameter values are listed by name only. Other MCPs answer 409 `not_api_mcp`. MCPs of other tenants answer 404.
readPath, query & header parameters 2
mcp_id (path)stringrequiredMCP id (the `id` of an MCP, not its slug).
include_operations (query)booleanoptionaltrue adds every OpenAPI operation with whether it is selected.
No request body.
curl --request GET \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/mcps/a1b2c3d4/api-config' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Scopes Try it in the playground
/mcps/{mcp_id}/api-configChange a REST API MCP's configuration
Merges the sent fields into the saved configuration and republishes the tools (`tool_diff`). Sending `base_url` or `remote_connector_id` (even unchanged), and nonempty `fixed_params`, need credentials:write. 400 `no_operations_selected` when nothing would be exposed, `invalid_operation_override` for unknown operations, `spec_missing` when switching to OpenAPI without a document. 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. Send the quoted `version` from the latest read in If-Match (428 when missing, 412 when stale).
mcps:write+ credentials:write (conditional)Path, 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
Fields to change; everything else keeps its saved value, including values this API never returns (fixed parameter values, URL query strings). `openapi: null` switches to one generic request tool.
accessobject | nulloptionalApiAccessRules object
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.
Also accepts null.
base_urlstringoptionalBase URL requests are sent to. Needs credentials:write: the saved credentials are sent there.
docs_textstring | nulloptionalmax_response_bytesinteger | nulloptionalopenapiobject | nulloptionalApiOpenApiPatch object
enable_generic_fallbackbooleanoptionaloverridesmap<string, object | null>optionalKeyed by operation (`GET /pets`). An object merges into the saved override (a sent `fixed_params` replaces the saved map); null removes the override.
Map value specification
ApiOperationOverride object
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.
Also accepts null.
preview_tokenstringoptionalA new document from POST /mcps/api:preview.
source_urlstringoptionalA new document URL, fetched now.
spec_base64stringoptionalA new document, base64 encoded.
spec_textstringoptionalA new document as JSON or YAML text.
Unknown fields are rejected in this object.
Also accepts null.
remote_connector_idstring | nulloptionaltimeout_snumber | nulloptionalUnknown fields are rejected in this object.
curl --request PATCH \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/mcps/a1b2c3d4/api-config' \
--header 'Authorization: Bearer <management-key>' \
--header 'If-Match: "r4"' \
--header 'Content-Type: application/json' \
--data '{
"openapi": {
"overrides": {
"GET /pets": {
"name": "list_all_pets"
}
}
},
"timeout_s": 20
}'
Authentication, errors & retry rules Scopes Try it in the playground
/mcps/{mcp_id}/api-config/access-testTest the saved access rules
Whether the saved rules allow one request, which rule decided and, for OpenAPI MCPs, the operation the path maps to.
readPath, query & header parameters 1
mcp_id (path)stringrequiredMCP id (the `id` of an MCP, not its slug).
Full request body specification application/json
methodstringrequiredHTTP method.
pathstringrequiredRequest path, for example /invoices/42.
tagsarray<string>optionalOpenAPI tags to test with; by default the matching operation's tags.
Array item specification
stringUnknown fields are rejected in this object.
curl --request POST \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/mcps/a1b2c3d4/api-config/access-test' \
--header 'Authorization: Bearer <management-key>' \
--header 'Content-Type: application/json' \
--data '{
"method": "GET",
"path": "/pets/42"
}'
Authentication, errors & retry rules Scopes Try it in the playground
/mcps/{mcp_id}/api-config/resyncResync the OpenAPI document
Downloads the document again from its source URL and reports added and removed operations. `apply=true` saves it: overrides of operations that still exist are kept and new operations are saved turned off. 409 `spec_uploaded` for an uploaded document, `not_openapi` for generic MCPs, `no_operations_selected` when `apply=true` would leave no operation selected (a report without `apply` returns it in `error`). `apply=true` needs If-Match with the quoted `version` from the latest read (428 when missing, 412 when stale); without `apply`, If-Match is optional. 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)Path, query & header parameters 2
mcp_id (path)stringrequiredMCP id (the `id` of an MCP, not its slug).
apply (query)booleanoptionaltrue saves the fetched document (needs If-Match); false or omitted only reports what would change.
Full request body specification application/json
fetch_headersmap<string, string>optionalHeaders for downloading a protected document; used once, never stored. Needs credentials:write.
Map value specification
stringUnknown fields are rejected in this object.
curl --request POST \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/mcps/a1b2c3d4/api-config/resync' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Scopes Try it in the playground
/mcps/{mcp_id}/api-config/selection-previewPreview which operations would become tools
Applies candidate access rules and override changes to the saved document without saving.
readPath, query & header parameters 1
mcp_id (path)stringrequiredMCP id (the `id` of an MCP, not its slug).
Full request body specification application/json
Candidate rules and override changes, applied like the PATCH would. Omitted fields use the saved values.
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.
overridesmap<string, object | null>optionalKeyed by operation (`GET /pets`). An object merges into the saved override (a sent `fixed_params` replaces the saved map); null removes the override.
Map value specification
ApiOperationOverride object
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.
Also accepts null.
Unknown fields are rejected in this object.
curl --request POST \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/mcps/a1b2c3d4/api-config/selection-preview' \
--header 'Authorization: Bearer <management-key>' \
--header 'Content-Type: application/json' \
--data '{
"access": {
"allow": [
{
"tags": [
"read"
]
}
]
}
}'
Authentication, errors & retry rules Scopes Try it in the playground