Skip to main content

Integration Guide

Replace <YOUR_MCP_BASE_URL> in the examples with your deployment's HTTPS base URL, without a trailing slash. This can be https://mcpgateway.quilr.ai, https://mcpgateway.quilrai.com, or another exact hostname assigned under quilrai.com. Copy the base from your Quilr dashboard; the placeholder includes https://.

MCP endpoints, authentication methods, and connection examples for integrating AI agents with MCP Gateway.

Administrator rollout guides

For detailed prerequisites, organization controls, OAuth fields, and troubleshooting, start with AI client setup. Choose GitHub Copilot, Copilot Studio / Microsoft 365, Claude and Claude Code, Cursor, ChatGPT and Codex, or Gemini Enterprise and Gemini CLI.

MCP Endpoint URL​

Each MCP gets a unique endpoint URL, shown as Quilr gateway on its server card in Settings > AI Gateway > MCP Gateway and on your deployment's user dashboard. Point your AI agent to this complete URL. Use the same <YOUR_MCP_BASE_URL> for MCP and OAuth requests.

<YOUR_MCP_BASE_URL>/<your-mcp-slug>/mcp

Authentication Methods​

MCP Gateway separates the credential your AI client uses to reach the gateway from the credential the gateway uses to reach the upstream MCP server.

Client to Gateway​

MethodUse WhenClient Sends
API tokenProgrammatic access to non-OAuth or static-key MCPs.Authorization: Bearer <api-token> plus mcpuser: user@company.com.
Gateway OAuth proxy tokenThe AI client supports OAuth with the gateway.A gateway-issued Bearer token from the MCP OAuth authorize/token flow.
OAuth passthroughThe upstream MCP expects the client to perform OAuth directly with the upstream provider.The upstream provider's Bearer token.
OneMCP OAuth proxy tokenThe client connects to the dashboard-provided OneMCP URL, such as <YOUR_MCP_BASE_URL>/quilrone/mcp.A gateway-issued OneMCP Bearer token.

API Token Authentication​

Send a Bearer token with a user identifier header for per-user tracking.

Authorization: Bearer <token>
mcpuser: user@company.com
  • Create API tokens in the server's Settings > API tokens (not shown on OAuth servers). See API Tokens.
  • Each token is scoped to a specific agent
  • The mcpuser header supplies trusted caller attribution for per-user tracking; it is not proof that the named user completed SSO
  • The mcpuser email must belong to an allowed company domain

Gateway OAuth Proxy Tokens​

OAuth-capable MCP clients can authenticate to the gateway through the gateway's OAuth endpoints. After the user signs in, the token endpoint returns a stable proxy token. The proxy token is scoped to the MCP server, or to OneMCP for the /quilrone/mcp endpoint.

OAuth Passthrough​

In OAuth passthrough mode, the gateway advertises or relays the upstream OAuth metadata and the AI client obtains an upstream access token itself. The gateway accepts that upstream Bearer token on the direct per-MCP endpoint, forwards it to the upstream MCP server, and uses token claims such as email, preferred_username, upn, or sub for logging when available.

OAuth passthrough MCPs are not exposed through OneMCP and do not use gateway token storage, refresh, user dashboard connections, or proxy tokens.

Gateway to Upstream MCP​

Upstream Auth ModeDescription
No authThe upstream MCP does not require authentication. The gateway still authenticates and authorizes clients before forwarding calls.
OAuth - Dynamic Client Registration (DCR)The gateway registers as an OAuth client with the MCP server and manages per-user upstream tokens.
OAuth - Manual credentialsAn admin enters an OAuth client ID and OAuth client secret in the Connect with OAuth step. Use this for providers that do not support DCR.
OAuth passthroughThe client manages upstream OAuth and sends the upstream Bearer token through the gateway.
Upstream API keyAn admin stores an upstream key, shared by the whole tenant or brought by each user. The gateway sends it as a bearer header, custom header, or query parameter when calling the upstream MCP. Change it in Settings > General > Upstream authentication.

To choose a mode when you add a server, see Adding MCP Servers. For manual OAuth setup steps, see MCP Provider Setup. For OneMCP unified access, memory tools, and inline authentication, see OneMCP.

Non-OAuth MCPs can also receive the authenticated Quilr user identity in a gateway-generated X-User-Claims JSON header. Turn it on with Forward user claims in the server's Settings > General. It works for direct MCP and OneMCP requests and is off by default. See Claims forwarding for configuration, schema, and trust requirements.

Token-Based Connection Example​

This is an administrator diagnostic for a direct non-OAuth server. Replace the token, email, backend path, and diagnostic User-Agent with values matching the token's configured agent. In production, bind the token to the actual client rather than overriding its identity. For end-to-end session validation, use a real MCP client and complete initialization; see validation.

# Connect to MCP endpoint with token auth
curl -X POST '<YOUR_MCP_BASE_URL>/your-mcp-slug/mcp' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your-api-token>" \
-H "mcpuser: user@company.com" \
-H "User-Agent: <token-configured-agent-key>" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"method": "tools/list",
"id": 1
}'

Connect an AI client​

Use the OneMCP URL from the user dashboard (for example <YOUR_MCP_BASE_URL>/quilrone/mcp) to get every gateway-managed MCP through one connection, or a single MCP's Quilr gateway URL. OAuth passthrough MCPs are only available on their own URL (see OneMCP).

The gateway speaks MCP over Streamable HTTP. Compatible clients can authenticate with OAuth: on the first request the gateway answers 401 with a pointer to its OAuth metadata, the client registers itself, and your browser opens to sign in with your company account. Use the client's OAuth flow rather than copying a token. Review the authentication compatibility limits and validate your client version before rollout. Before an MCP's tools work, connect it once on the user dashboard (or through the in-chat connector card).

Connect Cursor​

Add the server to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json in a project:

{
"mcpServers": {
"quilr-onemcp": {
"url": "<YOUR_MCP_BASE_URL>/quilrone/mcp"
}
}
}

Open Cursor's MCP settings, start the sign-in for quilr-onemcp, and complete it in the browser.

Check the connection​

  1. Without signing in, confirm the URL is right. A 401 with a WWW-Authenticate header that contains resource_metadata means you reached the gateway:

    curl -i -X POST '<YOUR_MCP_BASE_URL>/quilrone/mcp' \
    -H "Content-Type: application/json" \
    -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
  2. After signing in, list the client's tools. With OneMCP and dynamic tool calling on, expect list_mcp_connections, find_relevant_tools and call_tool, plus the memory tools when Memories enabled is on, and the most-used tools of any server with tool lists on. With it off, expect each allowed MCP's tools, prefixed with the MCP's name.

  3. Ask the client to list available connectors. MCPs under Connection needed still need a one-time connect.

If sign-in succeeds but calls are refused, check that the client is allowed under Allowed Agents and that you can reach the MCP under access control.

Limits​

These limits apply to every MCP request, on an MCP's own endpoint and on OneMCP. The values below are the defaults; your deployment can set different ones.

LimitDefaultWhat happens
MCP request body32 MiBA larger request is refused with HTTP 413 and a JSON-RPC error. Nothing is sent upstream.
Time to receive a request body60 secondsA body not received in full within this time is refused with HTTP 408.
Tool result32 MiBA larger result is replaced by a tool error (isError: true) that says the result is too large. The upstream tool call has already run, so any change it made has happened. Ask for less data, for example with filters or pagination.

Agent Configuration​

  • Each AI agent (OpenAI, Claude, Cursor, etc.) connects to the Quilr gateway URL shown on the server card, or to OneMCP
  • The gateway identifies agents by their User-Agent header keyword
  • Choose which MCPs each agent can reach with Allowed Agents on the MCP Gateway page (see Agents Configuration), or per server in Settings > General > Access control (see Access Control)