API & MCP 5 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 and, if you belong to more than one organization, choose the one this connection works in.
  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.

One organization per connection

Each MCP connection works in exactly one organization: the one you picked when you signed in. It stays there even if you switch organizations in the web app, and switching in the web app never changes what your AI agent can see.

To work in a different organization, reconnect the Catalio server in your client and pick the other organization when you sign in. To use two organizations side by side, add Catalio twice under different names (for example catalio and catalio-demo) and sign each one in to its own organization.

If your client reports that the connection has no organization, reconnect it once. That happens with connections made before organizations were required.

Claude Connectors Directory

You can also add the official Catalio MCP server from Claude’s Connectors Directory. Open the Catalio connector manage page in Claude, then complete Catalio OAuth when prompted to connect the Catalio connector.

Catalio no longer ships Slack or Microsoft Teams chat integrations. Use Catalio MCP (or the web app) for AI-assisted work with your catalog. Org Teams in Catalio are groups of users inside your organization — not Microsoft Teams.

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