# Installation

Set up API access and connect your AI agent to **YOUR-ORIGIN** (your app
hostname -- the URL you use to sign in).

## 1. Create a workspace API key

1. Sign in to your workspace.
2. Open **Settings -> Integrations** (owners only).
3. Create a key with a descriptive label (`cursor-agent`, `n8n`, etc.).
4. **Copy the secret immediately** -- it is shown once on create or roll.

Keys look like `ufa_...`. They authenticate both the REST API and workspace MCP.

## 2. Store the key securely

Pick one pattern and stick to it:

**Environment variable (recommended for CI and shells):**

```bash
export UFA_API_KEY="ufa_..."
export UFA_ORIGIN="https://YOUR-ORIGIN"
```

**Local file (recommended for desktop agents):**

```bash
mkdir -p ~/.config/outreach-agent
printf '%s' 'ufa_...' > ~/.config/outreach-agent/api_key
chmod 600 ~/.config/outreach-agent/api_key
```

Optional config file for origin (used by the CLI):

```bash
cat > ~/.config/outreach-agent/config.json <<'EOF'
{
  "origin": "https://YOUR-ORIGIN"
}
EOF
chmod 600 ~/.config/outreach-agent/config.json
```

Never commit keys, embed them in skills, or paste them into shared documents.

## 3. Verify connectivity

```bash
export UFA_API_KEY="ufa_..."
export UFA_ORIGIN="https://YOUR-ORIGIN"

# Workspace summary
curl -s -H "X-ApiKey: $UFA_API_KEY" \
  "$UFA_ORIGIN/api/v1/workspace" | jq .

# MCP endpoint (expect 405 -- GET is not allowed; POST is used for MCP)
curl -s -o /dev/null -w '%{http_code} %{content_type}\n' \
  -H "X-ApiKey: $UFA_API_KEY" \
  "$UFA_ORIGIN/mcp"
```

## Workspace MCP

Streamable HTTP at `YOUR-ORIGIN/mcp`. Same key as REST.

### Cursor

**Settings -> MCP -> Add server** (HTTP):

```json
{
  "mcpServers": {
    "workspace-outreach": {
      "url": "https://YOUR-ORIGIN/mcp",
      "headers": {
        "X-ApiKey": "ufa_YOUR_KEY"
      }
    }
  }
}
```

Prefer reading the key from your secure store when configuring -- do not leave
plaintext keys in shared project config if the repo is collaborative.

### Claude Code / Cursor CLI

Same HTTP block in your MCP config. Bearer auth also works:

```
Authorization: Bearer ufa_...
```

### Claude Desktop (stdio bridge)

Desktop apps that only support stdio need `mcp-remote`:

```json
{
  "mcpServers": {
    "workspace-outreach": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://YOUR-ORIGIN/mcp",
        "--header",
        "X-ApiKey: ufa_YOUR_KEY"
      ]
    }
  }
}
```

Install globally if you prefer:

```bash
npm install -g mcp-remote
mcp-remote https://YOUR-ORIGIN/mcp --header "X-ApiKey: ufa_YOUR_KEY"
```

### MCP tools available

| Tool | Action |
|------|--------|
| `whoami` | Workspace summary |
| `list_prospects` | Search/list prospects |
| `get_prospect` | Single prospect |
| `list_tags` | Tags |
| `list_sequences` | Sequences + steps |
| `list_templates` | Message templates |
| `append_prospects` | Import (dedupes LinkedIn URL) |
| `create_tag` | Create tag |
| `assign_tag` | Attach tag to prospects |
| `enroll_prospects` | Enroll in sequence |

Search, connect, message, approvals, and suppressions require the
[REST API](../public-api.md) or the [`ufa` CLI](./scripts/ufa.sh).

See [Workspace MCP](../mcp.md) for full details.

## Operator MCP (multi-book coaches)

If you operate **multiple client workspaces** (done-for-you / coach seat), use
**operator keys** (`ufa_op_...`) against `YOUR-ORIGIN/mcp/operator` -- not
workspace keys. See [Operator MCP](../mcp-operator.md).

## Agent skill (optional)

Copy the distributable skill so your agent loads outreach workflows and
guardrails:

```bash
# Cursor personal skills
mkdir -p ~/.cursor/skills/workspace-outreach
cp docs/agents/skill/SKILL.md ~/.cursor/skills/workspace-outreach/
cp docs/agents/skill/reference.md ~/.cursor/skills/workspace-outreach/

# Or Claude Code personal skills
mkdir -p ~/.claude/skills/workspace-outreach
cp docs/agents/skill/SKILL.md ~/.claude/skills/workspace-outreach/
cp docs/agents/skill/reference.md ~/.claude/skills/workspace-outreach/
cp docs/agents/scripts/ufa.sh ~/.claude/skills/workspace-outreach/scripts/
chmod +x ~/.claude/skills/workspace-outreach/scripts/ufa.sh
```

Edit `SKILL.md` and set `YOUR-ORIGIN` in the Authentication section to your
hostname.

## CLI wrapper (optional)

[`scripts/ufa.sh`](./scripts/ufa.sh) is a thin REST helper. Requires
`UFA_ORIGIN` (or `origin` in `~/.config/outreach-agent/config.json`).

```bash
export UFA_ORIGIN="https://YOUR-ORIGIN"
export UFA_API_KEY="$(cat ~/.config/outreach-agent/api_key)"

./docs/agents/scripts/ufa.sh whoami
./docs/agents/scripts/ufa.sh channels
./docs/agents/scripts/ufa.sh prospects --limit 20
./docs/agents/scripts/ufa.sh sequences
./docs/agents/scripts/ufa.sh --help
```

## Troubleshooting

| Symptom | Fix |
|---------|-----|
| `401 Invalid or missing API key` | Key wrong, revoked, or missing header |
| `429` with `Retry-After` | Write throttle -- back off; search counts as a write |
| MCP returns HTML / redirect | Wrong origin or cookie auth -- use `X-ApiKey` on `/mcp` |
| Search `400` | Channel not connected, demo mode, or invalid Sales Nav filter |
| Send `reason: daily_limit` | Quota spent for that channel/action -- wait for reset |
| Send `reason: suppressed` | Prospect matches do-not-contact -- remove suppression first |
| Duplicate approval items | Do not retry connect/message under HITL -- check approvals first |