Client access API
After an MCP is added and configured, these operations hand it out: what a client needs to connect, MCP API tokens for clients that cannot sign users in, which agents may use it, and who is connected. Try them with your own key in the MCP Management API playground.
Client setup
GET /mcps/{mcp_id}/client-setup returns, without secrets:
direct.url: the MCP's own endpoint,https://<gateway>/<slug>/mcp.onemcp.url: your organization's OneMCP endpoint, andonemcp.included(false when the MCP is hidden from OneMCP in its settings).direct.auth_methods: how clients authenticate.sign_in: the client signs the user in through the gateway (MCP clients that support MCP authorization prompt for it).api_token: an MCP API token plus the user's email in themcpuserheader (MCPs that do not use OAuth).upstream_oauth: OAuth passthrough MCPs, where the client brings the provider's token.direct.templates,direct.token_templates(only for MCPs that take MCP API tokens) andonemcp.templates: ready-to-paste configuration for MCP clients (mcpServersJSON, VS Codeservers, a Claude Code command line), with<MCP_API_TOKEN>and<USER_EMAIL>placeholders.sign_in_link: the sign-in link to hand to users.
Sign-in link
GET /mcps/{mcp_id}/sign-in-link returns a link to hand to the people who use the MCP, for example on an internal page or in an onboarding message:
{"mcp_id": "a1b2c3d4", "url": "https://mcpgateway.example.com/user/dashboard?connect=a1b2c3d4",
"connection": "oauth", "requires_user_action": true}
The link opens the Quilr user dashboard. Each person signs in to Quilr as themselves; the dashboard then starts this MCP's connect step. connection says what that is: oauth (sign in to the provider, for OAuth MCPs), user_key (save their own API key, for MCPs in per-user key mode) or null (nothing to do; the dashboard just shows the MCP). The link carries no credential and connects no one by itself, the same link works for everyone, and people without access to the MCP see a message instead. GET /mcps/{mcp_id}/users then shows who has connected.
OAuth client rotation
GET /mcps/{mcp_id}/oauth-client shows which OAuth client an OAuth MCP signs people in with: the last characters of the client id (client_id_hint), never the secret, and whether it can be rotated. Only clients your organization supplied (custom: true) can be; clients the gateway registered itself are managed by the gateway.
PUT /mcps/{mcp_id}/oauth-client replaces the client secret, and optionally the client id. It needs credentials:write and If-Match.
- A new
client_secretalone keeps everyone connected: existing sign-ins renew with the new secret. For a public client (no secret), send"client_secret": "-". - A new
client_idalso needsreconnect_users.truedeletes every person's connection to the MCP, so each signs in again with the new client (send them the sign-in link).falsekeeps existing connections on the previous client until it stops working at the provider; new sign-ins use the new client.reconnect_users: truealso works without a new client id: it signs everyone out again, for example to finish a request that was interrupted.
The response reports rotation.connections_dropped. MCPs without a gateway OAuth client answer 409 not_oauth_mcp; gateway-registered clients 409 oauth_client_not_custom.
MCP API tokens
An MCP API token lets a client that cannot sign users in (a CI job, a server-side agent) call one MCP. It is bound to one MCP and one agent: requests must come from a client whose User-Agent matches that agent, and name the end user in the mcpuser header so access rules, DLP and audit apply to that user. MCPs that use OAuth answer 409 oauth_mcp_uses_sign_in.
POST /mcps/{mcp_id}/tokens with {"name", "agent"} issues a token. It is a create: send an Idempotency-Key (see idempotency and recovery). The secret is in token.secret in that response only; a retry with the same key returns the same token. GET /mcps/{mcp_id}/tokens lists tokens without secrets and DELETE /mcps/{mcp_id}/tokens/{token_id} revokes one. These are the same tokens the console shows for the MCP.
Agents
An agent is a kind of MCP client, recognized by its User-Agent. GET /agents lists the built-in agents and your custom ones. POST /agents with {"keyword", "display_name"} adds a custom agent for an in-house client; it is allowed on every MCP. DELETE /agents/{keyword} removes a custom agent from every MCP. Built-in agents cannot be deleted (409 built_in_agent).
GET /mcps/{mcp_id}/agents shows which agents may use an MCP, and PUT /mcps/{mcp_id}/agents/{agent} with {"enabled": true|false} allows or blocks one. This is MCP configuration: it needs settings:write and If-Match with the version from the read (see versions and If-Match). The same list is access_control.allowed_agents in the MCP's settings.
User connections
GET /user-connections lists the users of your organization with how many MCPs are in each state; GET /user-connections/{email} shows one user's MCPs, and GET /mcps/{mcp_id}/users one MCP's users. States:
States are computed from stored state and may be a few minutes old (generated_at).
DELETE /mcps/{mcp_id}/users/{email}/connection deletes the user's stored credentials for the MCP (their provider sign-in, gateway session token and personal upstream credential); the user must connect again. It needs connections:write. It does not change access rules: to keep a user out, add them to access_control.denied_users in the MCP's settings.
Endpoint reference
/agentsList agents
Built-in and custom agents. Each is matched against the client User-Agent.
readPath, query & header parameters 2
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.
No request body.
curl --request GET \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/agents?limit=50' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Scopes Try it in the playground
/agentsCreate a custom agent
Adds an agent for an in-house client. It is allowed on every MCP of the tenant. 409 `agent_exists` when the keyword is taken by a built-in or custom agent.
agents:writeFull request body specification application/json
display_namestringrequiredkeywordstringrequiredMatched against the client User-Agent (case-insensitive); stored lowercase.
Unknown fields are rejected in this object.
curl --request POST \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/agents' \
--header 'Authorization: Bearer <management-key>' \
--header 'Content-Type: application/json' \
--data '{
"display_name": "Acme Bot",
"keyword": "acme-bot"
}'
Authentication, errors & retry rules Scopes Try it in the playground
/agents/{keyword}Delete a custom agent
Deletes the custom agent and removes it from every MCP. Built-in agents answer 409 `built_in_agent`.
agents:writePath, query & header parameters 1
keyword (path)stringrequiredAgent keyword from `GET /agents`.
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/agents/acme-bot' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Scopes Try it in the playground
/agents/{keyword}Read an agent
The agent and, for every MCP, whether it may use it.
readPath, query & header parameters 1
keyword (path)stringrequiredAgent keyword from `GET /agents`.
No request body.
curl --request GET \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/agents/acme-bot' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Scopes Try it in the playground
/mcps/{mcp_id}/agentsRead which agents may use an MCP
Every agent of the tenant with whether it may use this MCP. `version` is the MCP configuration version used by the If-Match of the write.
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/agents' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Scopes Try it in the playground
/mcps/{mcp_id}/agents/{agent}Allow or block an agent on an MCP
Adds the agent to, or removes it from, the MCP's allowed agents (settings `access_control.allowed_agents`). A request that changes nothing keeps the version. Send the quoted `version` from the latest read in If-Match (428 when missing, 412 when stale).
settings:writePath, query & header parameters 3
mcp_id (path)stringrequiredMCP id (the `id` of an MCP, not its slug).
agent (path)stringrequiredAgent keyword from `GET /agents`.
If-Match (header)stringrequiredQuoted `version` (ETag) from the latest read of this resource.
Full request body specification application/json
enabledbooleanrequiredtrue allows the agent.
Unknown fields are rejected in this object.
curl --request PUT \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/mcps/a1b2c3d4/agents/cursor' \
--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}/client-setupRead client setup
The MCP's own endpoint and the tenant OneMCP endpoint, how clients authenticate (`sign_in`: the client signs the user in through the gateway; `api_token`: an MCP API token plus the user's email in the `mcpuser` header; `upstream_oauth`: the client brings the provider token), whether the MCP is included in OneMCP and ready-to-paste client configuration with placeholders. 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/client-setup' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Scopes Try it in the playground
/mcps/{mcp_id}/tokensList MCP API tokens
Tokens issued for this MCP, newest first, without secrets. The Quilr console lists the same tokens.
readPath, query & header parameters 3
mcp_id (path)stringrequiredMCP id (the `id` of an MCP, not its slug).
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.
No request body.
curl --request GET \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/mcps/a1b2c3d4/tokens?limit=50' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Scopes Try it in the playground
/mcps/{mcp_id}/tokensIssue an MCP API token
Issues a token for a client that cannot sign users in. Clients send it as `Authorization: Bearer` and name the end user in the `mcpuser` header; it only works for the chosen agent. OAuth MCPs answer 409 `oauth_mcp_uses_sign_in`. The secret is returned once in `token.secret`. 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`.
tokens:writePath, query & header parameters 2
mcp_id (path)stringrequiredMCP id (the `id` of an MCP, not its slug).
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
agentstringrequiredAgent keyword from GET /agents. The token only works for clients whose User-Agent matches this agent.
namestringrequiredDisplay name.
Unknown fields are rejected in this object.
curl --request POST \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/mcps/a1b2c3d4/tokens' \
--header 'Authorization: Bearer <management-key>' \
--header 'Idempotency-Key: create-files-mcp-2026-11-14' \
--header 'Content-Type: application/json' \
--data '{
"agent": "cursor",
"name": "CI runner"
}'
Authentication, errors & retry rules Scopes Try it in the playground
/mcps/{mcp_id}/tokens/{token_id}Revoke an MCP API token
Deletes the token; clients using it are refused from the next request.
tokens:writePath, query & header parameters 2
mcp_id (path)stringrequiredMCP id (the `id` of an MCP, not its slug).
token_id (path)stringrequiredMCP API token id (`token_id` from the list or create response).
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/tokens/3c1f9a2b-5d6e-4f70-8a9b-0c1d2e3f4a5b' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Scopes Try it in the playground
/mcps/{mcp_id}/usersList users of an MCP
Connection state of every user who set this MCP up or is affected by its rules. States: signed_in, available, needs_sign_in, sign_in_not_finished, not_signed_in_yet, turned_off_by_user, blocked_by_access_rules, mcp_turned_off. Computed from stored state; may be a few minutes old (`generated_at`).
readPath, query & header parameters 3
mcp_id (path)stringrequiredMCP id (the `id` of an MCP, not its slug).
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.
No request body.
curl --request GET \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/mcps/a1b2c3d4/users?limit=50' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Scopes Try it in the playground
/mcps/{mcp_id}/users/{email}/connectionRevoke a user's connection
Deletes the user's stored credentials for this MCP (provider sign-in, gateway session token and personal upstream credential); the user must connect again. Access rules are unchanged: to block the user, add them to settings `access_control.denied_users`.
connections:writePath, query & header parameters 2
mcp_id (path)stringrequiredMCP id (the `id` of an MCP, not its slug).
email (path)stringrequiredUser email (case-insensitive).
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/users/dana%40example.com/connection' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Scopes Try it in the playground
/user-connectionsList users
Every known user of the tenant with how many MCPs are in each connection state.
readPath, query & header parameters 2
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.
No request body.
curl --request GET \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/user-connections?limit=50' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Scopes Try it in the playground
/user-connections/{email}Read a user's MCP connections
Connection state of each MCP for one user. 404 when the user is unknown.
readPath, query & header parameters 3
email (path)stringrequiredUser email (case-insensitive).
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.
No request body.
curl --request GET \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/user-connections/dana%40example.com?limit=50' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Scopes Try it in the playground
/mcps/{mcp_id}/oauth-clientRead an MCP's OAuth client
Which OAuth client the MCP signs users in with (never the secret) and whether it can be rotated: only clients an administrator supplied can be; clients the gateway registered are managed by the gateway.
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/oauth-client' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Scopes Try it in the playground
/mcps/{mcp_id}/oauth-clientRotate an MCP's OAuth client
Replaces the client secret, and optionally the client id. A new secret alone keeps every user connected. A new client id needs `reconnect_users`: true deletes every user's connection so each signs in again with the new client; false keeps existing connections on the previous client until it stops working at the provider, while new sign-ins use the new one. 409 `oauth_client_not_custom` or `not_oauth_mcp` when there is nothing to rotate. Send the quoted `version` from the latest read in If-Match (428 when missing, 412 when stale).
credentials: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
client_idstringoptionalA new client id; omit to keep the current one.
client_secretstringrequiredThe client secret. Required on every rotation; "-" for a public client (no secret).
reconnect_usersbooleanoptionalRequired when client_id changes. true deletes every user's connection (each user signs in again); false keeps them working with the previous client until it stops working at the provider.
Unknown fields are rejected in this object.
curl --request PUT \
'https://mcpgateway.quilr.ai/mcpgateway/management/v1/mcps/a1b2c3d4/oauth-client' \
--header 'Authorization: Bearer <management-key>' \
--header 'If-Match: "r4"' \
--header 'Content-Type: application/json' \
--data '{
"client_id": "<new client id>",
"client_secret": "<new secret>",
"reconnect_users": true
}'
Authentication, errors & retry rules Scopes Try it in the playground
/mcps/{mcp_id}/sign-in-linkGet the user sign-in link
A link to hand to users, for example on an internal page. It opens the Quilr user dashboard: the user signs in to Quilr as themselves, then the dashboard starts this MCP's connect step (`connection`: oauth signs in to the provider, user_key asks for their own key). The link carries no credential and connects no one by itself; users without access to the MCP see a message instead. 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/sign-in-link' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Scopes Try it in the playground