Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.animam.ai/llms.txt

Use this file to discover all available pages before exploring further.

Animam exposes an OAuth 2.1 authorization server fully conformant with the MCP authorization spec. Any MCP client (Claude Desktop, claude.ai Custom Connectors, Cursor, or your own agent) can connect with zero manual configuration beyond the MCP server URL.

​
How it works

The standard OAuth 2.1 Authorization Code flow with PKCE:
  1. Discovery — client fetches https://api.animam.ai/.well-known/oauth-authorization-server to learn the endpoints
  2. Registration — client POSTs to /oauth/register (RFC 7591 DCR) and receives a client_id
  3. Authorize — client opens /oauth/authorize?response_type=code&client_id=...&code_challenge=...&code_challenge_method=S256 in a browser
  4. Consent — the tenant logs into animam.ai and approves the requested scopes
  5. Token exchange — client POSTs the received code to /oauth/token with its PKCE verifier
  6. API calls — client uses the returned access_token as Authorization: Bearer <jwt> on MCP requests
Access tokens live 15 minutes. Refresh tokens live 30 days and rotate on every use.

​
Endpoints

EndpointMethodPurpose
/.well-known/oauth-authorization-serverGETRFC 8414 metadata
/.well-known/oauth-protected-resourceGETRFC 9728 resource metadata
/.well-known/jwks.jsonGETPublic key for JWT verification
/oauth/registerPOSTRFC 7591 Dynamic Client Registration
/oauth/authorizeGETAuthorization endpoint (redirects to consent UI)
/oauth/tokenPOSTExchange code for access token + refresh rotation
/oauth/revokePOSTRFC 7009 token revocation
All endpoints live on https://api.animam.ai.

​
Scopes

ScopeDescription
mcp:corpus:readRead the tenant knowledge base (corpus)
mcp:corpus:writeCreate and modify corpus entries
mcp:segments:readRead segments and slots
mcp:segments:writeCreate and modify segments and slots
mcp:tools:readRead tool configuration
mcp:tools:writeCreate and modify tool configuration
mcp:conversations:readRead conversation history
mcp:visitors:readRead visitor profiles and memory
mcp:settings:readRead tenant settings
mcp:settings:writeModify tenant settings
mcp:billing:readRead plan usage and quota
Unknown scopes are silently filtered at consent time (RFC 6749 §3.3).

​
Security

  • PKCE S256 mandatory — no fallback to plain (OAuth 2.1 hardening)
  • Public clients only — token_endpoint_auth_method=none, no client_secret
  • Exact redirect_uri match — no wildcards, no substring matching
  • Single-use authorization codes — replay attempts return invalid_grant
  • Strict refresh token rotation — any reuse of a rotated refresh token triggers full-chain revocation
  • JWT access tokens RS256 — signed stateless, verifiable via JWKS, hashed in DB for early revocation
  • Rate limits — 5/h/IP on DCR, 30/min on token/revoke, 20/min on authorize

​
Example: register a client and start a flow

# 1. Register
curl -X POST https://api.animam.ai/oauth/register \
  -H 'Content-Type: application/json' \
  -d '{
    "client_name": "My MCP Client",
    "redirect_uris": ["http://localhost:3000/callback"],
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"],
    "token_endpoint_auth_method": "none",
    "scope": "mcp:corpus:read mcp:segments:read"
  }'
# → { "client_id": "animam-oauth-xxxxx", ... }

# 2. Generate PKCE verifier and challenge
CODE_VERIFIER=$(openssl rand -base64 32 | tr -d '=+/' | cut -c1-43)
CODE_CHALLENGE=$(printf '%s' "$CODE_VERIFIER" | openssl dgst -binary -sha256 | openssl base64 -A | tr '+/' '-_' | tr -d '=')

# 3. Open authorize URL in browser (user logs in and approves)
echo "https://api.animam.ai/oauth/authorize?response_type=code&client_id=animam-oauth-xxxxx&redirect_uri=http%3A%2F%2Flocalhost%3A3000%2Fcallback&scope=mcp%3Acorpus%3Aread&state=xyz&code_challenge=$CODE_CHALLENGE&code_challenge_method=S256"

# 4. Exchange code for tokens
curl -X POST https://api.animam.ai/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d "grant_type=authorization_code&code=<code>&redirect_uri=http://localhost:3000/callback&client_id=animam-oauth-xxxxx&code_verifier=$CODE_VERIFIER"
# → { "access_token": "eyJ...", "refresh_token": "...", "expires_in": 900, ... }

​
Connecting from Claude Desktop

Add Animam as a remote MCP server in your Claude Desktop config. Claude Desktop handles the entire OAuth flow (discovery + DCR + authorize + token exchange) transparently — you just approve the consent screen once.

​
Legacy ApiToken cohabitation

The MCP server accepts both OAuth JWT access tokens and legacy ApiToken Bearer tokens (created from the tenant dashboard). OAuth is preferred for all third-party integrations; ApiToken remains supported for internal scripts and CI pipelines.

​
Questions and feedback

For issues or feedback, contact the Animam team or open an issue at github.com/wellknownmcp/animam-ai.