Connections and OAuth API
Check whether an MCP is serving tools, fetch its tools now, and connect OAuth MCPs created through the API. Try them in the MCP Management API playground.
Connection state
GET /mcps/{mcp_id}/connection returns connection_state:
The response also lists connected_admins, the administrators with an OAuth connection to the MCP.
Refresh tools
POST /mcps/{mcp_id}/capabilities:refresh (scope mcps:write) fetches tools, resources and prompts from the upstream server now, as the administrator who issued the key, and replaces the cached lists. New tools may be held for review (held_tools); see tool reviews. A pending tool change that proposes exactly the fetched tool list is closed as applied; a change to any other list stays pending, so review it as usual.
Connect links
An OAuth MCP (auth.type oauth_dcr or oauth_login, or an OAuth catalog MCP) needs one OAuth sign-in with the provider before the gateway can fetch its tools. A connect link lets you finish that sign-in from a browser, without the console.
- Create the OAuth MCP (
POST /mcpswithauth.typeoauth_dcroroauth_login, or install an OAuth catalog MCP). The response contains aconnectobject with a single-useurlthat is valid for 15 minutes and itsexpires_at.POST /mcps/{mcp_id}/connect-linksissues a new link at any time. - Open the link in a browser, or send it to the person who should complete the provider sign-in. No Quilr sign-in is needed: whoever opens the link is sent to the provider's sign-in. The link's token is in the URL fragment, so the browser never sends it in the page request or to server logs, and the page removes it from the address bar at once.
- The page starts the provider's sign-in. After consent, the gateway saves the connection for the administrator who issued the management key, fetches the tools and shows a success page.
GET /mcps/{mcp_id}/connectionthen reportsreadyand lists that administrator inconnected_admins.
curl --request POST "$GW/mcpgateway/management/v1/mcps/e5f6a7b8/connect-links" \
--header "Authorization: Bearer $KEY"
{
"mcp_id": "e5f6a7b8",
"connect": {
"url": "https://mcpgateway.example.com/mcpgateway/management-connect#t=<token>",
"expires_at": "2026-11-14T10:15:00Z"
},
"request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f"
}
A connect link is a bearer credential for 15 minutes and can be used once. Whoever opens it first connects their provider account, and that connection is saved for the administrator who issued the management key. Share the link only with the person who should connect, over a private channel, and issue a new link if it may have leaked. An unused link stops working when it expires, when it is used, or when the issuing management key is revoked or expires.
End users connect with their own accounts later, as with MCPs added in the console. See OAuth connect. OAuth passthrough MCPs need no link.
How the connect page works
The connect page sends the token to POST /mcpgateway/management-connect/start with the body {"token": "<t>"}. This endpoint takes no authentication and is rate limited per client address. It answers mcp_id, mcp_name, authorization_url and request_id, and the page then opens authorization_url. You do not need to call it yourself; errors use the normal error shape.
POST /mcps/{mcp_id}/connect-links answers 409 oauth_not_applicable for an MCP that does not use gateway-managed OAuth.
Retrying an OAuth create or install with the same Idempotency-Key within 24 hours returns the original response (see idempotency and recovery). Its connect link is the stored one while it can still be used. When the stored link has expired, was used, or has less than 60 seconds left, the replay carries a new link for the same MCP instead: only connect.url and connect.expires_at change, and later retries return the new link while it is valid.
Endpoint reference
/mcps/{mcp_id}/capabilities:refreshRefresh tools
Fetches tools, resources and prompts from the upstream server now, as the administrator who owns the key, and replaces the cached lists (new tools may be held for review). A pending tool change proposing exactly the fetched tool list is closed as applied; a change to any other list stays pending. OAuth MCPs need that administrator's connection (409 `oauth_connection_required`); passthrough MCPs answer 409 `pending_first_client`.
mcps:writePath, query & header parameters 1
mcp_id (path)stringrequiredMCP id (the `id` of an MCP, not its slug).
Full request body specification application/json
No body, or an empty JSON object.
Unknown fields are rejected in this object.
curl --request POST \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/mcps/a1b2c3d4/capabilities:refresh' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Scopes Try it in the playground
/mcps/{mcp_id}/connect-linksIssue an OAuth connect link
A new single-use link (15 minutes) for an OAuth MCP whose sign-in the gateway manages. The link itself authorizes the connection: whoever opens it within 15 minutes, once, is sent to the provider's sign-in, and the connection they make is saved for the administrator who owns this management key (no console sign-in). Treat the URL as a short-lived credential and share it only with the person who should connect the account. The token is in the URL fragment; the landing page posts it to `POST /mcpgateway/management-connect/start` (`{"token": "..."}`, no authentication; answers `{mcp_id, mcp_name, authorization_url}`, or 404 `connect_link_not_found`, 409 `connect_link_used`, 410 `connect_link_expired` / `connect_link_revoked`, 409 `key_owner_unavailable`, 403 `management_disabled_for_tenant`, 429 `rate_limited`, 502 `oauth_initiation_failed`). 409 `oauth_not_applicable` for MCPs that do not use gateway-managed OAuth.
mcps:writePath, query & header parameters 1
mcp_id (path)stringrequiredMCP id (the `id` of an MCP, not its slug).
Full request body specification application/json
No body, or an empty JSON object.
Unknown fields are rejected in this object.
curl --request POST \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/mcps/a1b2c3d4/connect-links' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Scopes Try it in the playground
/mcps/{mcp_id}/connectionRead connection state
`ready`: tools are cached. `pending_connection`: an OAuth MCP waiting for its upstream sign-in (issue a connect link, or connect from the Quilr console). `fetch_failed`: the last tool fetch failed (see `last_fetch_errors`). `pending_first_client`: an OAuth passthrough MCP whose tools appear when the first client connects.
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/connection' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Scopes Try it in the playground