Authentication

This page is about signing in to the MCP server. The REST API signs in differently, with an email and password and a bearer token: see REST API.

The MCP server is an OAuth 2.1 resource server. Access is bound to a Casafari account with an MCP subscription: a token carries exactly that account's rights. Casafari does not use OAuth scopes; rights are per tool and resolved from the account on every call. The canonical, agent-facing version of this page is casafari.com/auth.md.

#Discovery

A request without a token answers:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token", resource_metadata="https://mcp.casafari.com/.well-known/oauth-protected-resource"

1. Fetch the protected resource metadata, https://mcp.casafari.com/.well-known/oauth-protected-resource. Its resource is the server's canonical URL: send it as the resource parameter in every authorization and token request, because tokens are bound to it as their audience.
2. Fetch the authorization server metadata, https://api.casafari.com/.well-known/oauth-authorization-server, for the registration, authorization and token endpoints.

#Sign in on behalf of a person

1. Register (once): POST to the registration endpoint with your client name and redirect URIs, grant_types ["authorization_code", "refresh_token"] and token_endpoint_auth_method none. Keep the client_id.
2. Authorize: send the person to the authorization endpoint with PKCE (S256), state and resource. They sign in with their Casafari account and approve.
3. Exchange the code at the token endpoint, again with resource and the PKCE verifier.
4. Call the server with Authorization: Bearer <access_token>.
5. Refresh with the refresh token when expires_in runs out. A 401 with error="invalid_token" on a token that used to work means it expired or was revoked: refresh it, and if that fails, authorize again. Keep the client; do not register again.

#Agents without a person

An agent that runs unattended uses the client credentials grant. Such a client cannot register itself: Casafari issues a client_id and client_secret for the account, and the account owner hands them to the agent.

#Errors

#Questions about this

• What is the Casafari MCP server URL?
• What is the difference between Casafari MCP and the Casafari REST API?
• Which AI assistants and MCP clients work with Casafari MCP?
• Who can use Casafari MCP?
• Do I need an API key for Casafari MCP?