Skip to main content

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

FieldEffect
base_url, timeout_s, max_response_bytes, docs_textReplace the saved value.
accessReplaces the access rules: allow and deny lists of rules matching methods, path globs, keywords or OpenAPI tags. Deny wins; a nonempty allow list must match.
openapi.overridesPer operation ("GET /pets"): an object merges into the saved override (name, description, enabled, fixed_params; a sent fixed_params replaces the saved map), null removes the override.
openapi.enable_generic_fallbackAlso expose one generic request tool.
openapi.preview_token, source_url, spec_text, spec_base64A new OpenAPI document (at most one). Without one the saved document is kept.
openapi: nullSwitch to generic mode: one request tool guided by docs_text.
remote_connector_idReach the API through a Remote Connector; null stops using one.

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-preview with candidate access and overrides (applied like the PATCH would) lists every operation with whether it would be selected.
  • POST /mcps/{mcp_id}/api-config/access-test with {"method", "path"} reports whether the saved rules allow that request, which rule decided, and the operation the path maps to.
  • POST /api-access/test evaluates rules you have not saved (access in the body) against one request.
  • GET /api-access/presets returns named starting points such as read_only and no_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​

POST/api-access/test

Test candidate access rules

Evaluates rules you have not saved against one request.

REQUIRESread
Full request body specification application/json

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.

methodstringrequired

HTTP method.

min length: 1max length: 16
pathstringrequired

Request path, for example /invoices/42.

min length: 1max length: 4096pattern: ^/
tagsarray<string>optional

OpenAPI tags to test with; by default the matching operation's tags.

max items: 64
Array item specification
string

Unknown 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

GET/mcps/{mcp_id}/api-config

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

REQUIRESread
Path, query & header parameters 2
mcp_id (path)stringrequired

MCP id (the `id` of an MCP, not its slug).

include_operations (query)booleanoptional

true 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

PATCH/mcps/{mcp_id}/api-config

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

REQUIRESmcps:write+ credentials:write (conditional)
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

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 | nulloptional
ApiAccessRules object
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.

Also accepts null.

base_urlstringoptional

Base URL requests are sent to. Needs credentials:write: the saved credentials are sent there.

max length: 2048format: uri
docs_textstring | nulloptional
max length: 1048576
max_response_bytesinteger | nulloptional
greater than: 0
openapiobject | nulloptional
ApiOpenApiPatch object
enable_generic_fallbackbooleanoptional
overridesmap<string, object | null>optional

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

Also accepts null.

preview_tokenstringoptional

A new document from POST /mcps/api:preview.

max length: 128
source_urlstringoptional

A new document URL, fetched now.

max length: 4096format: uri
spec_base64stringoptional

A new document, base64 encoded.

spec_textstringoptional

A new document as JSON or YAML text.

Unknown fields are rejected in this object.

Also accepts null.

remote_connector_idstring | nulloptional
max length: 128
timeout_snumber | nulloptional
greater than: 0

Unknown 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

POST/mcps/{mcp_id}/api-config/access-test

Test the saved access rules

Whether the saved rules allow one request, which rule decided and, for OpenAPI MCPs, the operation the path maps to.

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

MCP id (the `id` of an MCP, not its slug).

Full request body specification application/json

methodstringrequired

HTTP method.

min length: 1max length: 16
pathstringrequired

Request path, for example /invoices/42.

min length: 1max length: 4096pattern: ^/
tagsarray<string>optional

OpenAPI tags to test with; by default the matching operation's tags.

max items: 64
Array item specification
string

Unknown 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

POST/mcps/{mcp_id}/api-config/resync

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

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

MCP id (the `id` of an MCP, not its slug).

apply (query)booleanoptional

true 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>optional

Headers for downloading a protected document; used once, never stored. Needs credentials:write.

write only
Map value specification
string
max length: 8192

Unknown 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

POST/mcps/{mcp_id}/api-config/selection-preview

Preview which operations would become tools

Applies candidate access rules and override changes to the saved document without saving.

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

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

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.

overridesmap<string, object | null>optional

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

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