Skip to main content

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, and onemcp.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 the mcpuser header (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) and onemcp.templates: ready-to-paste configuration for MCP clients (mcpServers JSON, VS Code servers, a Claude Code command line), with <MCP_API_TOKEN> and <USER_EMAIL> placeholders.
  • sign_in_link: the sign-in link to hand to users.

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_secret alone keeps everyone connected: existing sign-ins renew with the new secret. For a public client (no secret), send "client_secret": "-".
  • A new client_id also needs reconnect_users. true deletes every person's connection to the MCP, so each signs in again with the new client (send them the sign-in link). false keeps existing connections on the previous client until it stops working at the provider; new sign-ins use the new client. reconnect_users: true also 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:

StateMeaning
signed_inThe user's sign-in for this MCP is valid (or renews automatically).
availableThe MCP needs no sign-in; the user can use it.
needs_sign_inThe sign-in expired or was cleared; the user must sign in again.
sign_in_not_finishedThe user started signing in and did not finish.
not_signed_in_yetThe user has not signed in to this MCP.
turned_off_by_userThe user turned the MCP off for themselves.
blocked_by_access_rulesThe MCP's access rules exclude the user.
mcp_turned_offThe MCP is disabled.

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​

GET/agents

List agents

Built-in and custom agents. Each is matched against the client User-Agent.

REQUIRESread
Path, query & header parameters 2
limit (query)integeroptional

Page size, 1 to 200 (default 50).

min: 1max: 200default: 50
cursor (query)stringoptional

The `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

POST/agents

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

REQUIRESagents:write
Full request body specification application/json

display_namestringrequired
min length: 1max length: 200
keywordstringrequired

Matched against the client User-Agent (case-insensitive); stored lowercase.

min length: 1max length: 50pattern: ^[A-Za-z0-9][A-Za-z0-9-]*$

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

DELETE/agents/{keyword}

Delete a custom agent

Deletes the custom agent and removes it from every MCP. Built-in agents answer 409 `built_in_agent`.

REQUIRESagents:write
Path, query & header parameters 1
keyword (path)stringrequired

Agent 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

GET/agents/{keyword}

Read an agent

The agent and, for every MCP, whether it may use it.

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

Agent 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

GET/mcps/{mcp_id}/agents

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

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

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

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

REQUIRESsettings:write
Path, query & header parameters 3
mcp_id (path)stringrequired

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

agent (path)stringrequired

Agent keyword from `GET /agents`.

If-Match (header)stringrequired

Quoted `version` (ETag) from the latest read of this resource.

Full request body specification application/json

enabledbooleanrequired

true 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

GET/mcps/{mcp_id}/client-setup

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

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

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

GET/mcps/{mcp_id}/tokens

List MCP API tokens

Tokens issued for this MCP, newest first, without secrets. The Quilr console lists the same tokens.

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

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

limit (query)integeroptional

Page size, 1 to 200 (default 50).

min: 1max: 200default: 50
cursor (query)stringoptional

The `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

POST/mcps/{mcp_id}/tokens

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

REQUIREStokens:write
Path, query & header parameters 2
mcp_id (path)stringrequired

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

Idempotency-Key (header)stringrequired

Client-chosen token (1 to 200 characters) that makes retries safe: the same token and body within 24 hours returns the original response.

min length: 1max length: 200
Full request body specification application/json

agentstringrequired

Agent keyword from GET /agents. The token only works for clients whose User-Agent matches this agent.

min length: 1max length: 50
namestringrequired

Display name.

min length: 1max length: 200

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

DELETE/mcps/{mcp_id}/tokens/{token_id}

Revoke an MCP API token

Deletes the token; clients using it are refused from the next request.

REQUIREStokens:write
Path, query & header parameters 2
mcp_id (path)stringrequired

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

token_id (path)stringrequired

MCP 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

GET/mcps/{mcp_id}/users

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

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

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

limit (query)integeroptional

Page size, 1 to 200 (default 50).

min: 1max: 200default: 50
cursor (query)stringoptional

The `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

DELETE/mcps/{mcp_id}/users/{email}/connection

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

REQUIRESconnections:write
Path, query & header parameters 2
mcp_id (path)stringrequired

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

email (path)stringrequired

User 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

GET/user-connections

List users

Every known user of the tenant with how many MCPs are in each connection state.

REQUIRESread
Path, query & header parameters 2
limit (query)integeroptional

Page size, 1 to 200 (default 50).

min: 1max: 200default: 50
cursor (query)stringoptional

The `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

GET/user-connections/{email}

Read a user's MCP connections

Connection state of each MCP for one user. 404 when the user is unknown.

REQUIRESread
Path, query & header parameters 3
email (path)stringrequired

User email (case-insensitive).

limit (query)integeroptional

Page size, 1 to 200 (default 50).

min: 1max: 200default: 50
cursor (query)stringoptional

The `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

GET/mcps/{mcp_id}/oauth-client

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

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

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

PUT/mcps/{mcp_id}/oauth-client

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

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

client_idstringoptional

A new client id; omit to keep the current one.

min length: 1max length: 8192
client_secretstringrequired

The client secret. Required on every rotation; "-" for a public client (no secret).

min length: 1max length: 8192write only
reconnect_usersbooleanoptional

Required 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