Connect an AI Agent (MCP)

---
name: brain-dump-api
description: Use the Brain Dump API from agents and automations. Trigger when an agent needs to access a user's Brain Dump todos programmatically, connect the Brain Dump MCP server at https://braindump.latentedge.io/api/v1/mcp, configure bdk_ API key authentication, call https://braindump.latentedge.io/api/v1/todos CRUD endpoints, install the downloadable Brain Dump API skill, or use the bundled todo helper script.
---

# Brain Dump API

## Core Rules

- Use API base `https://braindump.latentedge.io` unless the user explicitly provides `BRAINDUMP_API_BASE` for another environment.
- Authenticate todo CRUD requests with a user-created Brain Dump API key that starts with `bdk_`.
- Send the key as `Authorization: Bearer $BRAINDUMP_API_KEY`. `X-API-Key: $BRAINDUMP_API_KEY` is also supported, but bearer auth is preferred.
- Use `/api/v1/todos` only for the account owned by the API key. Never ask for, infer, or use another user's key.
- Keep API keys out of source control, logs, screenshots, transcripts, and committed config.
- Use the OpenAPI contract for extra detail when needed: `https://braindump.latentedge.io/api/v1/openapi.json`.
- Prefer the MCP server over raw HTTP when the agent runtime supports MCP.

## MCP Server

Brain Dump hosts a remote MCP (Model Context Protocol) server at `https://braindump.latentedge.io/api/v1/mcp`.
It authenticates with the same `bdk_` API key and exposes five tools: `list_todos`, `create_todo`, `update_todo`, `delete_todo`, and `structure_dump` (turn a raw brain dump of free-form text into structured todos - the core product flow).

Connect from Claude Code:

```bash
claude mcp add --transport http braindump https://braindump.latentedge.io/api/v1/mcp --header "Authorization: Bearer $BRAINDUMP_API_KEY"
```

Or add it to any MCP client's `mcpServers` config:

```json
{
  "mcpServers": {
    "braindump": {
      "type": "http",
      "url": "https://braindump.latentedge.io/api/v1/mcp",
      "headers": { "Authorization": "Bearer bdk_your_key_here" }
    }
  }
}
```

Notes:

- The server is stateless streamable HTTP: tools only, no server push.
- The same subscription gate applies: without an active API subscription or beta entitlement the connection fails with `402`.
- `structure_dump` spends the account's shared AI quota (default 20/minute, 300/day). A leaked key can spend that quota, so rotate keys promptly if exposed.
- Todo reads, writes, and AI calls share their rate-limit buckets with the REST endpoints.

## Install This Skill

Install on another Codex or agent machine by downloading the zip and unpacking it into the agent's skills directory:

```bash
SKILLS_DIR="${CODEX_HOME:-$HOME/.codex}/skills"
mkdir -p "$SKILLS_DIR"
curl -L "https://braindump.latentedge.io/skills/brain-dump-api-skill.zip" -o /tmp/brain-dump-api-skill.zip
unzip -o /tmp/brain-dump-api-skill.zip -d "$SKILLS_DIR"
chmod +x "$SKILLS_DIR/brain-dump-api/scripts/braindump_todos.py"
```

For non-Codex agents, copy the `brain-dump-api` folder into that agent's custom skills/prompts directory and include `SKILL.md` as the API usage guide.

## Secrets Setup

Set the API key in the shell environment before running helper scripts or curl examples:

```bash
export BRAINDUMP_API_KEY="bdk_your_key_here"
export BRAINDUMP_API_BASE="https://braindump.latentedge.io"
```

For persistent local use, store those exports in a private shell profile or a local `.env` file that is ignored by git. Do not commit the key.

## Helper Script

Use the bundled helper when shell access is available and Python 3 is installed:

```bash
python "$SKILLS_DIR/brain-dump-api/scripts/braindump_todos.py" list
python "$SKILLS_DIR/brain-dump-api/scripts/braindump_todos.py" create --text "Send project update" --priority 2 --category work --minutes 25
python "$SKILLS_DIR/brain-dump-api/scripts/braindump_todos.py" update 123 --text "Send final project update" --priority 1
python "$SKILLS_DIR/brain-dump-api/scripts/braindump_todos.py" delete 123
```

The helper prints JSON by default. Add `--summary` before the command for readable text output.

## HTTP Examples

Use these examples when the helper is not available.

### List Todos

```bash
curl -sS "https://braindump.latentedge.io/api/v1/todos" \
  -H "Authorization: Bearer $BRAINDUMP_API_KEY"
```

### Create Todo

```bash
curl -sS -X POST "https://braindump.latentedge.io/api/v1/todos" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BRAINDUMP_API_KEY" \
  -d '{"text":"Send project update","priority":2,"category":"work","estimatedDurationMinutes":25}'
```

### Update Todo

```bash
curl -sS -X PUT "https://braindump.latentedge.io/api/v1/todos/123" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BRAINDUMP_API_KEY" \
  -d '{"text":"Send final project update","priority":1}'
```

### Delete Todo

```bash
curl -sS -X DELETE "https://braindump.latentedge.io/api/v1/todos/123" \
  -H "Authorization: Bearer $BRAINDUMP_API_KEY"
```

## Todo Fields

- `id`: integer todo ID returned by the API.
- `text`: required string, 1 to 5000 characters.
- `priority`: required integer from `1` to `4`; `1` is urgent and `4` is low priority.
- `category`: required string, usually a short label such as `work`, `home`, `errands`, or `general`.
- `estimatedDurationMinutes`: optional integer minutes or `null`.
- `createdAt`: Unix timestamp in seconds.

Create requires `text`, `priority`, and `category`. Update accepts any subset of `text`, `priority`, `category`, and `estimatedDurationMinutes`.

## Agent Workflow

- List todos first when the user references a todo by description instead of ID.
- For create requests without an explicit priority or category, use `priority: 3` and `category: "general"`, then tell the user those defaults were used.
- For update/delete requests, operate on the exact todo ID when available.
- Ask for confirmation before bulk deletes or broad updates unless the user gave an explicit, unambiguous instruction.
- After a create, update, or delete, summarize the changed todo ID and text.

## Common Errors

- `401`: Missing, malformed, expired, or revoked API key. Ask the user to create or provide a valid `bdk_` key.
- `402`: API subscription or lifetime beta entitlement is required.
- `404`: Todo ID does not exist for this API key's account.
- `429`: Rate limit hit. Wait before retrying.