auth.md
OAuth is the default way for MCP clients to connect. API keys remain for curl and scripts. Live homepage scores need a signed-in account and share the Free meter.
Audience
MCP clients connecting to DealScore, and programmatic clients calling REST. The public web form uses the same signed-in Free meter as keys and MCP.
MCP OAuth (primary)
Add https://cardealscore.com/api/mcp with no pre-shared key. The client discovers /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server, opens a browser for magic-link sign-in and consent, then calls MCP with Authorization: Bearer and an access token.
Scope is mcp (score deals, explain grades, health). Tokens are stored hashed. Dynamic client registration is at POST https://cardealscore.com/oauth/register. HTTPS Client ID Metadata Documents are also accepted.
API keys (secondary)
Sign in with an email magic link, then create or revoke keys on /keys. Same account as OAuth consent. Operator env keys (DEALSCORE_API_KEYS) remain as break-glass.
Sign in to create an API key (email magic link). Create and revoke keys on /keys. Live scores share a Free meter of 40 scored deals per month. Sign in on the homepage before live scoring. Details: /docs/api#get-a-key.
x-api-key: YOUR_KEYAuthorization: Bearer YOUR_KEY
Send one of those on REST, or on MCP if the client cannot do OAuth:
POST https://cardealscore.com/api/scorePOST https://cardealscore.com/api/explain- Streamable HTTP
https://cardealscore.com/api/mcp
GET https://cardealscore.com/api/health is open and does not take a key.
Markdown twin
Agents can fetch /auth.md or send Accept: text/markdown to this page.