Skip to main content

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:

StateMeaning
readyTools are cached and served.
pending_connectionAn OAuth MCP waiting for its OAuth connection. Issue a connect link.
fetch_failedThe last tool fetch failed. last_fetch_errors has fixed codes: auth_failed, timeout, tls_error, unreachable, protocol_error, no_capabilities or unknown.
pending_first_clientAn OAuth passthrough MCP: tools appear when the first client connects with its own token.

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.

ResponseMeaning
409 oauth_connection_requiredThe OAuth MCP has no connection for the key's administrator. Issue a connect link.
409 upstream_credential_requiredThe MCP needs a credential before tools can be fetched. Set one with upstream credentials.
409 pending_first_clientOAuth passthrough MCPs cannot be refreshed by the gateway.

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
OAuth create or install
or POST connect-links
Share
Single-use link
Valid 15 minutes
Open
No Quilr sign-in
Provider sign-in
Ready
Connection saved
Tools fetched
QuilrAI
  1. Create the OAuth MCP (POST /mcps with auth.type oauth_dcr or oauth_login, or install an OAuth catalog MCP). The response contains a connect object with a single-use url that is valid for 15 minutes and its expires_at. POST /mcps/{mcp_id}/connect-links issues a new link at any time.
  2. 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.
  3. 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.
  4. GET /mcps/{mcp_id}/connection then reports ready and lists that administrator in connected_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"
}
Treat a connect link like a password

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.

StatusCodeMeaning
400invalid_requestMissing or malformed token, or extra fields.
403management_disabled_for_tenantManagement is turned off for the organization.
404connect_link_not_foundUnknown link, or its MCP was removed.
409connect_link_usedThe link was already used. Issue a new one.
409key_owner_unavailableThe key's administrator left the organization. Issue a new key and link.
409oauth_not_applicableThe MCP no longer uses gateway-managed OAuth.
410connect_link_expiredThe link is older than 15 minutes. Issue a new one.
410connect_link_revokedThe management key that issued the link was revoked or expired.
429rate_limitedToo many attempts from this address. Retry after Retry-After.
502oauth_initiation_failedThe provider sign-in could not be started; the link was not used.

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​

POST/mcps/{mcp_id}/capabilities:refresh

Refresh 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`.

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

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

GET/mcps/{mcp_id}/connection

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

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

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