Authentication
CIN MCP uses OAuth 2.0 with Hyland IAM. Every user signs in with their own Hyland account, and every tool call runs with that user's environment and roles. There are no shared service accounts.
Overview
CIN MCP authentication occurs through the following sequence of events:
- The AI client calls the server without a token. The server answers HTTP 401 with a
WWW-Authenticateheader pointing to its protected-resource metadata. - The client reads the metadata, finds Hyland IAM, and starts an authorization code flow with PKCE using your client ID and secret.
- The user signs in to Hyland in the browser. IAM redirects back to the client's registered redirect URI with a code, which the client exchanges for an access token.
- The client sends the token on every MCP request (
Authorization: Bearer …). - On each tool call, the server exchanges the user's token with IAM for a token scoped to the product the tool belongs to, and then it calls the product with it.
Endpoints
The following endpoints are called during authentication:
| Item | Value |
|---|---|
| MCP server | https://cin-mcp.ai.app.hyland.com/mcp |
| Protected-resource metadata | https://cin-mcp.ai.app.hyland.com/.well-known/oauth-protected-resource/mcp |
Clients discover Hyland IAM from the metadata automatically; users only need the server URL.
Scopes
The server advertises these scopes, and clients request them automatically:
| Scope | Purpose |
|---|---|
| Identify the user. |
| Gain access to the CIN MCP server. |
environment_authorization | Puts the user's Hyland environment in the token. Without it, tools fail with "no tenant environment for this request". |
OAuth Clients
When CIN MCP is deployed for you, Hyland generates a client ID named cin-claude-[customerid] and registers it for your environment and an app key. Your
administrator receives the client ID and its secret through a secure channel and enters
them when adding the connector or MCP server.
IAM matches redirect URIs exactly, including host, port, and path. These are registered for the supported clients:
| Client | Redirect URI | Client setting |
|---|---|---|
| Claude desktop app and Cowork (organization connector) | https://claude.ai/api/mcp/auth_callback | None; used automatically |
| Claude Code | http://localhost:8080/callback | --callback-port 8080 |
| OpenAI Codex | http://127.0.0.1:1455/callback | callback_port = 1455 |
The client secret is required. If it's missing or wrong, the browser sign-in still shows success but the token exchange fails, and the client keeps asking the user to sign in again.
Token Lifetime
Access tokens are valid for 15 minutes. When a token expires, the AI client asks the user to sign in again.
Product Token Exchange
The server never passes the user's token to the products. For each tool call it exchanges the token with IAM for a product token:
| Tool Area | App Key Exchanged For |
|---|---|
| cin-agent-builder |
| Knowledge Discovery | hxai-discovery |
| content-lake |
The exchange succeeds only if your environment is subscribed to that product and the user has a role for it. Otherwise, only that product's tools fail. See Subscription and Roles for more information.
Agent Builder Agents
When a tool agent calls CIN MCP tools, Agent Builder sends the invoking user's Hyland token with each call, so the agent's tool calls run with the invoking user's permissions. See Use CIN MCP in Agent Builder for more information.
Security Notes
- Keep the client secret in a password manager or secrets store. Never put it in chat, email, tickets, or shared files. If a secret is exposed, contact Hyland Support to rotate it.
- Sign-in uses PKCE, so a stolen authorization code can't be redeemed by another process.
- The server removes tokens, secrets, and signed URLs from error messages before returning them.