API Guides 4 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 reuses your existing Catalio permissions exactly as the web app does — there’s no separate MCP-specific permission set. Those permissions come from two independent systems, and it’s worth knowing which one governs what:

  • Organization role (Admin, Editor, Contributor, Viewer) governs organization membership administration — who can invite, remove, and change the role of other members. With one exception noted below, it does not by itself grant access to any requirement, persona, or use case.
  • Resource access is granted per resource, through sharing. Each grant carries a relation — Viewer, Editor, Admin, or Owner — on that specific resource, and your MCP session reaches a resource where you (or one of your teams) hold such a grant, or where the resource’s visibility already exposes it to you.
  • The exception: Organization Admin. An organization administrator bypasses the per-resource checks entirely and reaches every resource in the organization. This is a distinct administrator grant held by one of your teams at the organization level — it is not the same thing as the Admin value of the organization role above, and the two are checked separately.

So an MCP token reaches precisely the resources you can reach in the web app, no more — but note that outside the administrator case, a high organization role is not itself a key to the data, and a Contributor with the right grants may reach more than an Editor without them.

Note

Not every resource type carries its own visibility setting. Use cases, for example, are readable by any member of the organization that owns them rather than requiring a per-resource grant; access is still confined to your organization. Treat per-resource sharing as the control for resources that support visibility, not as a uniform barrier across every type.
  • 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.
  • 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

  • Permission Levels — the per-resource Viewer/Editor/Admin/Owner grants that decide what an MCP session can reach
  • Users — organization roles 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