# ForgetMe Opt-Out — MCP Guide

For humans: open **http://localhost:3456/** for the interactive guide and web UI.

## What this is

A service that submits data-removal / opt-out requests to people-search and data-broker websites on behalf of users. It exposes **MCP tools**, a **REST API**, and a **web UI**.

- **MCP HTTP:** `POST /mcp` (Streamable HTTP transport)
- **MCP stdio:** `node src/transports/stdio.js` (Claude Desktop / Claude Code)
- **Machine-readable info:** `GET /api/info`
- **Health:** `GET /health`

## Authentication

Pass keys via `Authorization: Bearer {key}` on HTTP/MCP HTTP, or in tool arguments for stdio.

| Key | Format | Used for |
|-----|--------|----------|
| Agent | `ak_...` | `register_user`, `list_users` |
| User | `uk_...` | Runs, profile, re_register, delete_user |
| Admin | env `ADMIN_KEY` | `admin_*` tools |

Agent keys are **not** self-service — an admin mints them via `admin_create_agent_key` or the `/admin` dashboard.

## Typical workflow

```
1. register_user      (agent_key + PII)     → user_id + api_key  [save api_key — shown once]
2. start_opt_out_run  (user_id + api_key)   → job_id
3. get_run_status     (job_id + api_key)    → poll every ~5s until status is done or error
4. get_run_results    (job_id + api_key)    → summary, email confirmations, manual sites
```

**Re-run after purge:** `re_register` (user_id + api_key + fresh PII) → `start_opt_out_run` again.

**Do not** hold a single tool call open waiting for the run to finish. Poll `get_run_status`.

## Cursor / remote HTTP MCP config

Add to Cursor MCP settings (adjust host for production):

```json
{
  "mcpServers": {
    "forgetme": {
      "url": "http://localhost:3456/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_AGENT_OR_USER_KEY"
      }
    }
  }
}
```

Use an **agent key** (`ak_...`) to register users. Use a **user key** (`uk_...`) to start and monitor runs.

## Claude Desktop (stdio)

```json
{
  "mcpServers": {
    "forgetme": {
      "command": "node",
      "args": ["C:/Code/p_forgetme_mcp/src/transports/stdio.js"]
    }
  }
}
```

Pass `agent_key` or `api_key` in tool arguments when calling tools.

## Tools reference

### User / agent tools

| Tool | Auth | Description |
|------|------|-------------|
| `register_user` | agent | Create user; returns `user_id` + `api_key` once |
| `get_user_profile` | user/agent | Masked profile, no raw PII |
| `re_register` | user/agent | Repopulate PII for a new run cycle |
| `delete_user` | user/agent | Delete user and job history |
| `list_users` | agent | List users for this agent |
| `start_opt_out_run` | user/agent | Queue run; optional `sites_filter` array |
| `get_run_status` | user/agent | Poll progress |
| `get_run_results` | user/agent | Final summary (terminal jobs only) |
| `list_runs` | user/agent | Run history for one user |
| `list_sites` | none | Broker inventory |
| `get_site_status` | user/agent | Latest result for user + site |

### Admin tools

| Tool | Description |
|------|-------------|
| `admin_create_agent_key` | Mint `ak_...` key (only issuance path) |
| `admin_list_agent_keys` | List agents |
| `admin_disable_agent_key` / `admin_enable_agent_key` | Toggle agent |
| `admin_delete_agent_key` | Delete agent; optional `cascade` |
| `admin_list_active_jobs` | Live queue state |
| `admin_list_all_jobs` | Paginated history |
| `admin_get_job` | Full job detail |
| `admin_list_users` | Paginated users (no PII) |
| `admin_add_site_config` | Add broker config JSON |
| `admin_set_site_credentials` | Set Radaris/MyLife login creds |

## REST API parity

All tools have REST equivalents under `/api/*`. See `master-build-spec.md` §10 or `GET /api/info`.

## PII policy

- Purged immediately on successful run (`done`).
- Retained up to 30 days on `error` for retry.
- Never returned by `get_user_profile` (masked metadata only).

## Testing

```bash
npx @modelcontextprotocol/inspector
# Connect to stdio: node src/transports/stdio.js
# Or HTTP: http://localhost:3456/mcp
```