Skip to main content
This page is for admins, reviewers and security teams evaluating the Lunacal MCP server (https://mcp.lunacal.ai/mcp) for use with Claude, Muse, ChatGPT and other MCP clients.

​
How authentication works

Authentication has two layers. AI assistants only ever deal with the first one.

​
1. AI assistant → mcp.lunacal.ai (OAuth 2.1, public client)

MCP clients connect using the standard MCP authorization flow:
  • They discover the server through /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server.
  • They register themselves dynamically (/register, RFC 7591). No client ID or client secret is issued to them.
  • They use the authorization code grant with PKCE (S256).
  • They send the resulting token as Authorization: Bearer to https://mcp.lunacal.ai/mcp.

​
2. mcp.lunacal.ai → Lunacal (OAuth 2.0, confidential client)

Behind the scenes, the MCP server is a single pre-registered, server-side OAuth client of the Lunacal platform. Its client secret never leaves Lunacal’s servers.
1

Consent

The user is sent to the Lunacal consent screen, which lists the read and write permissions being granted. If they aren’t signed in, they log in first.
2

Approval

When the user clicks Allow, Lunacal verifies a CSRF token (HttpOnly, SameSite=Strict cookie, 10-minute expiry) and checks redirect_uri against the registered list. It then issues a one-time authorization code.
3

Token exchange

The MCP server exchanges the code and its client secret for tokens. The code is single-use and expires after 10 minutes.
4

Rotation

Access tokens last 1 hour and refresh tokens 365 days. Every refresh rotates both tokens, and a used refresh token is rejected.
The client secret, registered redirect URIs and the /api/mcp/token and /api/mcp/refresh endpoints in the API documentation belong to layer 2. If you are connecting an AI assistant, you don’t need any of them.

​
Access levels

Lunacal currently grants a single access level that includes both read and write tools. To limit an assistant to read-only use, turn off the write tools in your AI client’s connector settings (where supported), or keep tool-call confirmation turned on. A read-only access option is on our roadmap.

​
Tools, permissions and side effects

All tools act only on the Lunacal account that approved the connection.
Most AI clients ask you to confirm before running a write tool. Review the details — especially attendee, date and time — before approving.

​
Expected responses

Each tool returns JSON in the MCP result content. Fields match the corresponding endpoint in the API documentation. Timestamps are ISO 8601 in UTC, so clients should convert them to the user’s timezone (returned by Get current user) before displaying them.

​
Failure handling

​
Revoking access

  • Remove the Lunacal connector in your AI client to revoke its access.
  • Access tokens are short-lived and are only ever sent to mcp.lunacal.ai.