# auth.md

CalcForms is an MCP server you connect to from ChatGPT (official app) or Claude (custom connector). Authentication is OAuth 2.1 (Authorization Code + PKCE), brokered by Supabase, with email one-time-code sign-in.

## For AI agents

- **MCP endpoint:** https://forms.badabingapp.cc/
- **Auth type:** OAuth 2.1 (Authorization Code + PKCE)
- **Protected resource metadata:** https://forms.badabingapp.cc/.well-known/oauth-protected-resource
- **Authorization server metadata:** https://forms.badabingapp.cc/.well-known/oauth-authorization-server
- **Bearer token usage:** send `Authorization: Bearer <token>` on requests to the MCP endpoint.
- **Scopes:** standard OpenID and email scopes from the authorization server.

## agent_auth

Machine-readable authentication metadata for agents:

```json
{
  "agent_auth": {
    "skill": "oauth2",
    "register_uri": "https://glbpeoausndrsjufjpco.supabase.co/auth/v1/oauth/clients/register",
    "resource": "https://forms.badabingapp.cc",
    "authorization_servers": [
      "https://glbpeoausndrsjufjpco.supabase.co/auth/v1"
    ],
    "issuer": "https://glbpeoausndrsjufjpco.supabase.co/auth/v1",
    "authorization_endpoint": "https://glbpeoausndrsjufjpco.supabase.co/auth/v1/oauth/authorize",
    "token_endpoint": "https://glbpeoausndrsjufjpco.supabase.co/auth/v1/oauth/token",
    "scopes_supported": [
      "openid",
      "profile",
      "email"
    ],
    "bearer_methods_supported": [
      "header"
    ],
    "grant_types_supported": [
      "authorization_code",
      "refresh_token"
    ],
    "registration_methods": [
      {
        "type": "dynamic_client_registration",
        "register_uri": "https://glbpeoausndrsjufjpco.supabase.co/auth/v1/oauth/clients/register"
      }
    ]
  }
}
```

## Registration flow

A complete, standalone OAuth 2.1 registration flow an agent can follow without any other document:

1. **Register a client (Dynamic Client Registration, RFC 7591).** POST to the registration endpoint with your client metadata:

   ```
   POST https://glbpeoausndrsjufjpco.supabase.co/auth/v1/oauth/clients/register
   Content-Type: application/json

   { "client_name": "My Agent", "redirect_uris": ["https://my-agent.example/callback"], "grant_types": ["authorization_code", "refresh_token"], "token_endpoint_auth_method": "none" }
   ```

   The response returns a `client_id` (public client; PKCE required).
2. **Authorize (Authorization Code + PKCE).** Redirect the user to the authorization endpoint:

   ```
   GET https://glbpeoausndrsjufjpco.supabase.co/auth/v1/oauth/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=openid%20profile%20email&code_challenge=CHALLENGE&code_challenge_method=S256
   ```

   The user signs in by email one-time code and approves. You receive an authorization `code` at your redirect URI.
3. **Exchange the code for tokens.** POST to the token endpoint:

   ```
   POST https://glbpeoausndrsjufjpco.supabase.co/auth/v1/oauth/token
   Content-Type: application/x-www-form-urlencoded

   grant_type=authorization_code&code=CODE&redirect_uri=REDIRECT_URI&client_id=CLIENT_ID&code_verifier=VERIFIER
   ```

   The response returns `access_token` and `refresh_token`.
4. **Call the MCP endpoint.** Send `Authorization: Bearer ACCESS_TOKEN` to `https://forms.badabingapp.cc/`. Refresh with `grant_type=refresh_token` when the access token expires.

## How a user connects

1. In ChatGPT, install the official CalcForms app (https://chatgpt.com/plugins/plugin_asdk_app_6a6f98aa999c819186ebb24ce0c78afb). In Claude, add `https://forms.badabingapp.cc` as a custom connector.
2. The client runs the OAuth flow; the user signs in by email (6-digit code).
3. Once connected, the agent can call CalcForms tools to build forms, read submissions, and export data.

Questions: wisebubbler@gmail.com