# AI agents for your workspace

Connect Cursor, Claude Code, Claude Desktop, or any MCP-capable agent to your
workspace. Agents can list and import prospects, enroll sequences, run searches,
send outreach, and clear approval queues -- using the same API keys you create in
**Settings -> Integrations**.

This guide works on any branded deployment. Replace `YOUR-ORIGIN` with your app
URL (the hostname you sign in on, e.g. `https://app.example.com`).

## What you get

| Integration | Best for |
|-------------|----------|
| **[Workspace MCP](./installation.md#workspace-mcp)** | Native agent tools -- list, import, enroll without shell scripts |
| **[Public REST API](../public-api.md)** | Full surface -- search, connect, InMail, approvals, suppressions |
| **[Agent skill](./skill/SKILL.md)** | Copy into Cursor/Claude so the agent knows your workflows and guardrails |
| **[`ufa` CLI](./scripts/ufa.sh)** | Optional shell wrapper for scripts and automation |

Coach/operator seats servicing **multiple** workspaces use a separate
[Operator MCP](../mcp-operator.md) (`ufa_op_...` keys) -- not workspace keys.

## Quick start

1. **Create an API key** -- Settings -> Integrations -> Create key. Copy the
   secret once; it cannot be retrieved later.
2. **Verify** -- `curl -s -H "X-ApiKey: YOUR_KEY" YOUR-ORIGIN/api/v1/workspace`
3. **Connect your agent** -- follow [Installation](./installation.md) for your
   client (Cursor, Claude Desktop, etc.)
4. **Optional** -- copy the [agent skill](./skill/SKILL.md) into your skills
   folder so the agent loads outreach workflows automatically.

## Documentation

| Doc | Contents |
|-----|----------|
| [Installation](./installation.md) | API key storage, MCP setup, skill install, CLI |
| [Use cases](./use-cases.md) | Workflows by persona -- solo, team, done-for-you |
| [Agent skill](./skill/SKILL.md) | Distributable `SKILL.md` for coding agents |
| [API reference](./skill/reference.md) | REST route cheat sheet |
| [Workspace MCP](../mcp.md) | MCP tool list and client config |
| [Operator MCP](../mcp-operator.md) | Multi-book operator tools |
| [Public REST API](../public-api.md) | Full semantics, throttling, error reasons |
| [OpenAPI spec](../openapi.json) | Machine-readable schema |

## Security

- Workspace keys (`ufa_...`) scope to **one workspace** only.
- Never commit keys to git, paste them into skills, or share them in chat logs.
- Roll or revoke compromised keys immediately in Settings -> Integrations.
- Write endpoints are throttled (60/min/key). Search counts as a write and
  spends a paid provider request -- do not put search in a tight retry loop.

## Service models

| Model | Typical agent role |
|-------|-------------------|
| **Independent** | You run your own book -- workspace key + MCP/REST |
| **Team / done-with-you** | Coach assists; you may still use workspace keys for your book |
| **Done-for-you** | Operator agent uses **Operator MCP** to approve sends across client books |

Human-in-the-loop (`hitl`) routes outbound through an approval queue. Agents
must check pending approvals before retrying connect/message calls.