Authentication

Qoris MCP supports two authentication methods for connecting to your workspace:

API Key

Simple authentication using a project API key. Best for direct integration and scripting.

OAuth 2.0

User-delegated access via OAuth with consent. Best for MCP clients like Cursor and Claude Code.

API Key

API keys provide direct, project-scoped access. Each key is tied to a user and project. Generate keys from your project’s MCP tab in the Qoris dashboard.

Method 1: Query Parameter

Pass the API key as a query parameter in the MCP URL:

https://mcp.qoris.ai/mcp?api_key=YOUR_API_KEY

This is your personal MCP URL — each user has a different URL based on their API key. Convenient for quick setup and MCP clients that support URL-based auth.

Method 2: Authorization Header (Recommended)

Pass the API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

More secure than query parameters (keys don’t appear in URLs or logs). Use this for production.

API Key Format

Prefix: qoris_ (keys starting with this are validated as API keys)
Length: 38 characters total (qoris_ + 32 random chars)
Storage: Keys are hashed; the raw key is only shown once at creation

API keys provide full access to your project. Keep them secure and never commit them to version control.

OAuth 2.0

OAuth 2.0 enables MCP clients (Cursor, Claude Code, etc.) to request access on behalf of users. Users sign in and approve access via a consent page. This flow supports apps that cannot securely store API keys.

Flow Overview

Discovery — Client fetches OAuth metadata from well-known endpoints
Client Registration — Client registers dynamically (DCR) or uses pre-registered client
Authorization — User is redirected to consent page, signs in if needed, selects workspace, approves
Token Exchange — Client exchanges authorization code (+ PKCE verifier) for access token
MCP Access — Client uses access token as Bearer token for MCP requests

Discovery Endpoints

OAuth Authorization Server (RFC 8414):

GET https://mcp.qoris.ai/.well-known/oauth-authorization-server

Returns: issuer, authorization_endpoint, token_endpoint, registration_endpoint, scopes_supported, code_challenge_methods_supported, etc. OAuth Protected Resource (RFC 9728):

GET https://mcp.qoris.ai/.well-known/oauth-protected-resource
GET https://mcp.qoris.ai/.well-known/oauth-protected-resource/mcp

Returns: resource, authorization_servers, scopes_supported, bearer_methods_supported.

Endpoints

Endpoint	Method	Description
`/oauth/register`	POST	Dynamic Client Registration (DCR)
`/oauth/authorize`	GET	Authorization request — redirects to consent
`/oauth/token`	POST	Token exchange (code → access token) or refresh
`/oauth/client/<client_id>`	GET	Public client info (for consent UI)
`/oauth/authorize/approve`	POST	Consent completion (Clerk auth required)
`/oauth/connections`	GET	List user’s OAuth connections
`/oauth/connections/<token_id>`	DELETE	Revoke a connection

Dynamic Client Registration (DCR)

Clients register themselves with client_name and redirect_uris:

POST /oauth/register
Content-Type: application/json

{
  "client_name": "Cursor MCP",
  "redirect_uris": ["http://localhost:49311/callback"]
}

Response includes client_id. DCR deduplication: if a client with the same client_name and redirect_uris already exists, the existing client is returned (200) instead of creating a duplicate.

Authorization Code Flow with PKCE

Generate code_verifier (random) and code_challenge (S256 hash)

Redirect user to:

GET /oauth/authorize?client_id=...&redirect_uri=...&response_type=code
  &code_challenge=...&code_challenge_method=S256&state=...

User lands on consent page (https://app.qoris.ai/oauth/consent?client_id=...&...)
User signs in (Clerk), selects project/workspace, approves
Frontend calls /oauth/authorize/approve with code_challenge, project_id, etc.
Backend returns redirect_uri with ?code=...&state=...

Client exchanges code:

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=...&redirect_uri=...&client_id=...&code_verifier=...

Access Tokens

Format: Opaque Bearer token (not JWT)
Expiration: Access tokens do not expire. They remain valid until explicitly revoked.
Revocation: User can revoke via Connected Apps in the Qoris dashboard, or via DELETE /oauth/connections/<token_id>
Refresh tokens: Issued with access tokens; 30-day expiration. Used to obtain new access token when rotating.

Access tokens have no expiration. Revoke them from Connected Apps when you want to disconnect an app.

The consent page (https://app.qoris.ai/oauth/consent) shows:

App name (from client_name)
Requested scopes (save_memories, get_memories, update_memories, delete_memories, search_knowledge)
Project/workspace selector
Approve / Deny buttons

Users must be signed in via Clerk. After sign-in/sign-up, they are redirected back to consent with redirect_url preserved in session storage.

Connected Apps UI

Users manage OAuth connections from Workspace settings → MCP tab → Connected Apps. Each connection shows: app name, workspace, scopes, “Connected” date. Users can revoke access at any time. There is no expiration display — connections stay active until revoked.

MCP Scopes

Scope	Description
`save_memories`	Save new memories
`get_memories`	Retrieve/list memories
`update_memories`	Update existing memories
`delete_memories`	Delete memories
`search_knowledge`	Search project knowledge base

All scopes are granted by default when user approves. Clients may request a subset via the scope parameter.

Token Validation

Redis cache: Valid tokens are cached for 60 seconds to reduce DB load
Cache invalidation: On revoke, the token is removed from cache immediately
Bearer methods: Only header is supported (Authorization: Bearer <token>)

Choosing an Auth Method

Use Case	Recommended
Cursor, Claude Code, MCP clients with OAuth support	OAuth 2.0
Scripts, CI/CD, headless automation	API Key
Quick testing	API Key (query param)
Production integrations	API Key (header) or OAuth

Authentication and Knox

Authentication controls who can connect to Qoris MCP. Knox controls what an agent can safely do after it has access. Use Knox in addition to authentication when connected agents can:

run commands
write files
call MCP tools with untrusted input
create scheduled tasks
invoke subagents
perform actions that need audit or approval

For developer-agent workflows, start with the Knox Claude Code Plugin. For the broader governance model, see the Knox Overview.

Next Steps

Quick Start Guide — Setup with API key
MCP Tools Overview — Available tools
Knox Overview — Govern agent actions, hooks, policies, approvals, and audit
Technical Reference — Full integration details

​Authentication

API Key

OAuth 2.0

​API Key

​Method 1: Query Parameter

​Method 2: Authorization Header (Recommended)

​API Key Format

​OAuth 2.0

​Flow Overview

​Discovery Endpoints

​Endpoints

​Dynamic Client Registration (DCR)

​Authorization Code Flow with PKCE

​Access Tokens

​Consent Page

​Connected Apps UI

​MCP Scopes

​Token Validation

​Choosing an Auth Method

​Authentication and Knox

​Next Steps

Authentication

API Key

Method 1: Query Parameter

Method 2: Authorization Header (Recommended)

API Key Format

OAuth 2.0

Flow Overview

Discovery Endpoints

Endpoints

Dynamic Client Registration (DCR)

Authorization Code Flow with PKCE

Access Tokens

Consent Page

Connected Apps UI

MCP Scopes

Token Validation

Choosing an Auth Method

Authentication and Knox

Next Steps