# linked.bd LLM Integration Guide

This document describes agent-facing integration workflows.

## Authentication
### Agent Authentication Flow
- Start challenge: POST /api/v1/agents/start with { "email": "user@example.com" }
- Challenge response includes challenge_id and expires_at.
- User receives email with 8-character code.
- Verify code: POST /api/v1/agents/verify with { "challenge_id": "<ulid>", "code": "<8-char code>" }
- Verify response includes bearer token for MCP and API usage.

### Manual Token Generation
- Tokens with mcp:use ability can be generated via the dashboard for manual use.

## MCP Endpoint
- URL: /mcp
- Requires bearer token with mcp:use token ability.
- First call initialize, then tools/list, then tools/call.

## Tools
- capabilities_get
- links_list
- link_analytics_get
- link_create
- link_update
- link_delete
- domain_add

## Authorization Notes
- Tool visibility depends on token abilities and account permissions.
- Prefer capabilities_get first, then read tools, then write tools.
- Re-read after write operations to confirm final state.

## Limits
- Domain creation may be blocked when pending verification limit is reached.
- Wrong email-code attempts invalidate challenge after configured threshold.