How authorization works

MCP clients authorize against Langmail with standard OAuth 2.1 discovery — no pre-shared client IDs, no API keys. This page documents the flow as implemented, for anyone debugging a connection or building their own MCP client. The parties involved:

Role	URL
Resource server (the MCP server)	`https://mcp.langmail.me`
Authorization server (Langmail’s identity service)	`https://auth.langmail.me`
Login page (unauthenticated users land here)	`https://app.langmail.me/login`

The flow

The first request gets a 401

A request to https://mcp.langmail.me/mcp without a bearer token returns 401 with a pointer to the resource metadata:

Response header

WWW-Authenticate: Bearer realm="mcp", resource_metadata="https://mcp.langmail.me/.well-known/oauth-protected-resource"

Discover the protected resource

Request

curl https://mcp.langmail.me/.well-known/oauth-protected-resource

Response

{
  "authorization_servers": ["https://mcp.langmail.me"],
  "bearer_methods_supported": ["header"],
  "resource": "https://mcp.langmail.me"
}

Discover the authorization server

Request

curl https://mcp.langmail.me/.well-known/oauth-authorization-server

Response

{
  "issuer": "https://mcp.langmail.me",
  "authorization_endpoint": "https://auth.langmail.me/api/auth/oauth2/authorize",
  "token_endpoint": "https://auth.langmail.me/api/auth/oauth2/token",
  "registration_endpoint": "https://auth.langmail.me/api/auth/oauth2/register",
  "userinfo_endpoint": "https://auth.langmail.me/api/auth/oauth2/userinfo",
  "scopes_supported": ["openid", "email", "offline_access"],
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["none"],
  "resource": "https://mcp.langmail.me"
}

The issuer is the MCP server’s own URL, while the functional endpoints live on auth.langmail.me. Clients only need to follow the endpoints in this document.

The registration endpoint accepts dynamic client registration (RFC 7591) without prior credentials, rate-limited per IP. MCP clients typically register as a public client with a loopback redirect:

Registration request

{
  "client_name": "My MCP client",
  "redirect_uris": ["http://127.0.0.1:33418/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none",
  "application_type": "native",
  "scope": "openid email offline_access"
}

Redirect URIs are matched exactly at authorization time, so register the precise URI you will use, including the port.

The user signs in and consents

The client opens the authorization URL with a PKCE challenge:

https://auth.langmail.me/api/auth/oauth2/authorize?response_type=code
  &client_id=<CLIENT_ID>
  &redirect_uri=http://127.0.0.1:33418/callback
  &scope=openid+email+offline_access
  &code_challenge=<S256_CHALLENGE>
  &code_challenge_method=S256
  &state=<STATE>

A user without a session is sent to the Langmail login page first (Google sign-in is optional). Then a consent screen shows what the named client is asking for; approving redirects back to the client’s redirect_uri with an authorization code. Every dynamically registered client goes through consent — there are no silent grants.

Exchange the code for tokens

Request

curl -X POST https://auth.langmail.me/api/auth/oauth2/token \
  -d grant_type=authorization_code \
  -d code=<CODE> \
  -d redirect_uri=http://127.0.0.1:33418/callback \
  -d client_id=<CLIENT_ID> \
  -d code_verifier=<PKCE_VERIFIER>

The response contains an access_token and, because offline_access was granted, a refresh_token. Public clients send no client secret; the PKCE verifier binds the exchange to the client that started the flow.

Call the MCP server

Request header

Authorization: Bearer <ACCESS_TOKEN>

The MCP server validates the token against the authorization server’s userinfo endpoint and resolves the caller to their @langmail.me mailbox. Every tool call then operates on that mailbox — tokens are per-user, and a token can never reach another user’s mail.

Tokens

Access tokens are opaque — treat them as bearer credentials, not as JWTs to inspect.
Refresh tokens are issued when offline_access is granted, so clients can stay connected without re-prompting you to sign in.
Ending access: remove the server from your MCP client — it discards its tokens, and without the refresh token access lapses. There is no dashboard for reviewing individual grants yet.

Requirements on the user

The signed-in account must belong to a Langmail user with an active @langmail.me mailbox. Accounts without one are rejected at the MCP server with 401 invalid_token — sign up at app.langmail.me first.

Authorization gives a client access to the tools the server exposes for your mailbox — currently read access to mail and read-write access to calendars. See the tool reference for the exact surface.

Get started

Connect your agent

Guides

Concepts

How authorization works

The flow

Tokens

Requirements on the user

​The flow

​Tokens

​Requirements on the user

The flow

Tokens

Requirements on the user