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 Catalio account as your web login, authenticated via Catalio OAuth 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 Catalio as the authorization server, then starts the OAuth2 flow.
  4. You sign in with your existing Catalio credentials on the Catalio sign-in screen.
  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 Catalio OAuth 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 to Catalio. 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 to Catalio. 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 like other signed-in Catalio activity in your organization.

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
Account suspended The token is valid, but the matching Catalio account is suspended

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 on the Catalio sign-in screen.

Next Steps