MCP Authentication

How authentication works — API keys, auth.md agent registration, and connecting agents to LiveFolio.

Getting an API Key

Go to Settings → API Keys in the dashboard
Click Generate Agent Key
Give it a name (e.g., "Claude Code", "Cursor")
Copy the key — it's shown only once

The key format: lf_agent_xxxxxxxxxxxx

Using Your Key

Include the key as a Bearer token in the Authorization header:

{
  "mcpServers": {
    "livefolio": {
      "url": "https://livefolio.cloud/api/mcp",
      "transport": "sse",
      "headers": {
        "Authorization": "Bearer lf_agent_xxxxxxxxxxxx"
      }
    }
  }
}

If your MCP client doesn't support custom headers, pass the key as a query parameter:

https://livefolio.cloud/api/mcp?key=lf_agent_xxxxxxxxxxxx

How Auth Works

Agent connects to /api/mcp
    │
    ▼
Authorization header or ?key= parameter extracted
    │
    ▼
API key validated against your organization
    │
    ▼
On success: organization context injected
    │
    ▼
Request proceeds — agent can call tools

Agent-Native Registration (auth.md)

LiveFolio implements the open auth.md protocol. Agents can autonomously register and acquire API keys — no human dashboard interaction needed.

Discovery

Agents discover auth endpoints from the protected resource metadata:

GET https://livefolio.cloud/.well-known/oauth-protected-resource

User Claimed Flow (OTP)

Register — initialize an anonymous session:
```
POST /api/agent/auth
```

Claim — send the user's email to trigger a 6-digit code:

POST /api/agent/auth/claim
{ "email": "user@example.com" }

Complete — user provides the code, session upgrades to persistent API key:
```
POST /api/agent/auth/claim/complete
{ "code": "123456" }
```

The full protocol guide is served at /auth.md:

curl https://livefolio.cloud/auth.md

Key Management

Name keys descriptively — "Claude Code (MacBook)" not "key1"
One key per agent — don't share keys between tools
Rotate regularly — generate new keys and revoke old ones
Revoke instantly — delete a key from Settings to invalidate all connections using it

Troubleshooting

"Unauthorized" error

Verify the key hasn't been revoked (check Settings → API Keys)
Check the header format: Authorization: Bearer lf_agent_...
Ensure the key belongs to the correct workspace

Agent can't discover auth endpoints

The /.well-known/oauth-protected-resource and /auth.md endpoints are public. If they're not reachable, check your instance URL.

Self-Hosted Auth

Self-hosted instances have different authentication behavior. See Self-Hosting: Configuration for details.