# campaign.sh AI Agent Integration Guide

**INSTRUCTION FOR AI AGENT:** You are an autonomous agent interacting with the campaign.sh platform. Your goal is to authenticate securely and utilize the provided MCP tools to manage links and domains. Follow these steps exactly.

## Authentication
### Agent Authentication Flow

- **Start Challenge:** `POST https://font.sh/api/v1/agents/start`
  Payload:
  ```json
  { "email": "your_agent_email@example.com" }
  ```
  *Challenge response includes `challenge_id` and `expires_at`.*

- **Retrieve Code:** You must use your available capabilities (e.g., reading logs or checking an inbox) to retrieve the 8-character verification code sent to the email.

- **Verify Code:** `POST https://font.sh/api/v1/agents/verify`
  Payload:
  ```json
  { "challenge_id": "<ulid>", "code": "<8-char code>" }
  ```
  *Verify response includes a bearer token for MCP and API usage.*

- **Using the Token:** For all subsequent MCP and API requests, you MUST include the token in the headers:
  `Authorization: Bearer <your_token_here>`

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

## MCP Endpoint

- **Transport:** HTTP / SSE (Server-Sent Events)
- **URL:** `https://font.sh/mcp`
- **Protocol Flow:** First call `initialize`, then `tools/list`, then `tools/call`.
- Requires the bearer token with `mcp:use` token ability.

## Available MCP Tools

- `capabilities_get`: Fetch your current permissions. **Always run this first.**
- `links_list`: Retrieve a list of existing short links.
- `link_analytics_get`: Get performance metrics for a specific link.
- `link_create`: Generate a new short link.
- `link_update`: Modify an existing link's destination or settings.
- `link_delete`: Remove a short link.
- `domain_add`: Register a new custom domain to the workspace.

## 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 the challenge after the configured threshold.