Catalio logo
Sign in
Banner image for MCP Authentication
API Guides • 3 min read

MCP Authentication

Connect AI agents like Claude Desktop and Claude Code to Catalio over MCP, and how the OAuth2 flow works.

Updated
On this page

Catalio exposes an MCP (Model Context Protocol) server so AI agents like Claude Desktop and Claude Code can query and work with your requirements, personas, use cases, and other Catalio data directly from a conversation. MCP access uses the same Auth0 credentials as your web login, authenticated via OAuth2 rather than an API key.

How It Works

  1. Your MCP client connects to https://catalio.ai/mcp.
  2. Catalio returns 401 Unauthorized with a WWW-Authenticate header pointing to Catalio’s protected resource metadata (per RFC 9728).
  3. Your MCP client follows that metadata to discover Auth0 as the authorization server, then starts the OAuth2 flow.
  4. You sign in with your existing Catalio credentials in the browser prompt.
  5. The client receives a short-lived access token and retries the connection, now authenticated as you.

No API key to create or rotate — your MCP client re-authenticates through Auth0 automatically when a token expires.

Connect Your MCP Client

Add Catalio as a remote MCP server in your client (Claude Desktop, Claude Code, or any MCP-compatible client), using this URL:

Plaintext 
https://catalio.ai/mcp

The first time you connect, your client will open a browser window for you to sign in via Auth0. After that, reconnects are silent — the client refreshes your token as needed. Refer to your MCP client’s own documentation for the exact steps to add a remote server, since this differs by client.

Example: A business analyst adds Catalio’s MCP endpoint to Claude Code. When Claude attempts to access requirements, the analyst is prompted to sign in via Auth0. After authentication, Claude can query and analyze requirements using the analyst’s own Catalio permissions.

Permissions

MCP access inherits your Catalio role and organization membership exactly as the web app does — there’s no separate MCP-specific permission set:

  • Your access token carries the same role (Viewer, Contributor, Editor, Admin) you have on the web.
  • A suspended Catalio account cannot obtain or use an MCP access token, the same as it can’t sign in to the web app.
  • All MCP activity is auditable through your organization’s Auth0 logs.

Error Responses

Message Meaning
No Bearer token provided Request was missing an Authorization: Bearer <token> header
Invalid or expired token The token failed validation, or has expired
User not found. Please complete registration first. The token is valid, but no Catalio account matches it

Any of these responses is a 401 and includes a WWW-Authenticate header pointing back to the discovery metadata, so a well-behaved MCP client can restart the OAuth flow automatically.

Troubleshooting

“My MCP connection isn’t working”

  • The access token may have expired — reconnecting should trigger a silent refresh.
  • Verify your Catalio account is Active, not suspended, in your organization’s user settings.
  • Double-check your MCP client is pointed at https://catalio.ai/mcp (not a cached or local address).
  • If prompted, re-authenticate via the Auth0 sign-in screen.

Next Steps

  • Users — roles, permissions, and account status
  • API Authentication — API-credential (client-credentials) auth for service-to-service integrations
  • JSON:API Overview — the REST API for programmatic access when you’re not using an MCP client