BoxDo Agents — API & MCP Server

What is BoxDo?

BoxDo is a team communication and project management app. Think of it as the intersection of Telegram and Notion — real-time chat combined with structured documentation. Each project has:

Messages — real-time chat with replies, reactions, voice messages, media, and file sharing
Tasks — todo items with status, priority, assignees, due dates, and checklists
Box — a structured daily document (like a shared notebook) that organizes tasks, questions, files, and links extracted from conversations
Members — team members with roles (admin/member) and notification preferences

What can an agent do with BoxDo?

By connecting an AI agent to BoxDo, it can act as your alter ego — with the same permissions and access to your projects. Use cases:

Read context

Read messages, tasks, and Box content to understand what the team is working on

Send updates

Post messages on your behalf — deploy notifications, status reports, answers to questions

Manage tasks

Create, update, and complete tasks — triage incoming work, set priorities and due dates

Multi-agent workflows

Build custom agent systems that monitor conversations and take action automatically

When an agent writes a message or creates a task, a small Agent badge appears so everyone knows it was AI-generated. The key used is recorded in each task/message via an agent_key_id reference, and every action is written to the agent audit log.

Quick Start

Get your API Key

Visit boxdo.com/agents/token to log in and generate an API key. The key looks like ak_7f3b... — copy it once, save it somewhere safe. You can revoke it anytime from BoxDo Settings.

Add BoxDo to Claude Code (single command)

Run this in your terminal. BoxDo is a remote HTTP MCP server — no npm install, no stdio, no extra dependencies:

claude mcp add --transport http boxdo \
  https://www.boxdo.com/api/mcp \
  --header "Authorization: Bearer ak_your_key_here" \
  --scope user

This registers BoxDo globally for Claude Code. The next time you start a session, the boxdo_* tools will be available automatically.

Start using it

Start a new Claude Code session. The BoxDo tools are now available. Try:

"List my BoxDo projects"

"Read the last 20 messages from project X"

"Send a message to project X saying: done!"

Staying up to date

The remote MCP above (https://www.boxdo.com/api/mcp) always runs the latest tools — updates ship on our side, so you never have to update anything. If you instead use the npm package (boxdo-mcp), pin it to @latest and restart your client to pick up new versions; it also prints an update notice on startup when a newer version is available. Note that the npm package also carries fewer tools than the remote MCP — see the availability column in the table below.

Available MCP Tools

All 29 tools below are available on the remote MCP (https://www.boxdo.com/api/mcp) — the setup in Quick Start. The older boxdo-mcp npm package exposes only the 13 marked Both; the 16 marked Remote only are not in it. Use the remote MCP unless you specifically need a local stdio server.

Tool	Description	Available in
`boxdo_whoami`	Get current user info (id, name, username)	Both
`boxdo_list_projects`	List all projects you're a member of	Both
`boxdo_get_project`	Get project details and the full member list with roles	Both
`boxdo_create_project`	Create a new group project (you become admin)	Remote only
`boxdo_archive_project`	Archive or unarchive a project (admin only)	Remote only
`boxdo_start_dm`	Start a direct message with a user (or return the existing DM)	Remote only
`boxdo_invite_member`	Invite a user to a group project (admin only)	Remote only
`boxdo_remove_member`	Remove a member from a project (admin only)	Remote only
`boxdo_search_users`	Find users by name, username, or phone to invite them	Remote only
`boxdo_read_messages`	Read messages from a project chat (paginated)	Both
`boxdo_send_message`	Send a message (shows Agent badge). Attach files (images/videos/documents) via the chat-media upload flow — see Attachments below	Both
`boxdo_delete_message`	Soft-delete your own message	Remote only
`boxdo_react`	Add or remove an emoji reaction on a message	Remote only
`boxdo_list_tasks`	List tasks (filter by status, priority)	Both
`boxdo_get_task`	Get full task details including checklist and context	Remote only
`boxdo_create_task`	Create a task with optional attachments, reminders and checklist	Both
`boxdo_update_task`	Update title, status, priority, assignee, due date, attachments, reminders, or archive	Both
`boxdo_delete_task`	Delete a task permanently	Both
`boxdo_manage_checklist`	Add, toggle, rename, or remove checklist items on a task	Both
`boxdo_read_box`	Read today's Box (structured document) for a project	Both
`boxdo_list_boxes`	List historical Box documents by date	Remote only
`boxdo_read_box_by_id`	Read a specific historical Box by ID	Remote only
`boxdo_search`	Search across messages, tasks, and Box content in your projects	Remote only
`boxdo_get_unread_counts`	Get unread counts per project and total	Remote only
`boxdo_mark_as_read`	Mark a project chat as read	Remote only
`boxdo_get_notifications`	Recent notifications (pings, mentions, task updates)	Remote only
`boxdo_list_apps`	List mini-apps (Shared Expenses + Shopping Lists) with a summary each — balances, who-owes-whom, shopping items. Omit project_id to aggregate across all your projects. Read-only	Both
`boxdo_list_agents`	List the Remote Agents you have access to — name, @handle, machine, online state, model, permission level, and session counts (including how many are waiting for an answer). Read-only	Remote only
`boxdo_request_upload_url`	Get a signed URL to upload a file to BoxDo storage (see Attachments flow below)	Both

Message Formatting

Messages sent via boxdo_send_message are rendered as Markdown (GFM + soft-breaks) on every client. Whatever you pass as content is stored verbatim — the clients do the rendering. What this means in practice:

Effect	Write in `content`
Line break (same paragraph)	`A single \n`
New paragraph	`Double \n\n`
Bold	`bold`
Italic	`italic`
Inline code	`code`
Code block	```lang\n...\n```
Bulleted list	`- item 1\n- item 2`
Numbered list	`1. first\n2. second`
Link	`[label](https://…)`
Blockquote	`> quoted line`
Mention a member	`@username (resolved client-side)`
Emoji	`Unicode characters directly (🎉, ✅, 🚀)`

Example — multi-line status update

{
  "content": "**Deploy status**\n\n- API: ✅ live\n- Web: ✅ live\n- iOS build 65: uploaded to TestFlight\n\nNext: watch error rate for 30 min."
}

Gotchas

• When writing the JSON body, newlines must be escaped as \n inside the string — not literal backslash + n characters. Most SDKs handle this automatically; double-check if you build the JSON manually.
• A single \n now renders as a line break on every client (web + iOS). Prefer \n\n between distinct sections so the content reads well even in very narrow previews.
• Trailing whitespace is trimmed server-side. Leading/trailing blank lines are removed before storage.
• HTML tags are NOT rendered — they're shown as plain text. Use Markdown, not HTML.

Common Recipes

Patterns for frequent user requests. Each recipe is a short sequence of tool calls — follow the order, resolve names to UUIDs before you act.

“Send a message to Mario” — resolving a name

The user mentions a person by first name. You need to map that name to a user UUID before you can act.

Call boxdo_list_projects to cache all projects + their DM partner names.
If the name matches a DM partner → you already have the project id, go to step 4.
Otherwise, for each group project, call boxdo_get_project and scan members[] for a displayName or username match. If found in a group, ask the user: “Send it to Mario in project X, or start a private DM?”
If no match anywhere, call boxdo_search_users (global directory), present candidates to the user, then boxdo_start_dm with their id.
Finally boxdo_send_message with the chosen project id.

Ambiguity rule: if two members match the same first name, ASK before sending. Never guess.

“Catch me up” — daily triage

boxdo_get_unread_counts — get per-project unread totals.
boxdo_get_notifications — recent pings and mentions.
For each project with unread > 0, call boxdo_read_messages with the unread count as limit, then summarize.
Do NOT call boxdo_mark_as_read automatically — let the user decide.

“Create a task for Marco” — task with named assignee

Resolve Marco's user id via boxdo_get_project on the target project (admin-only actions require admin, but creating a task only needs membership).
boxdo_create_task with assignee: his user id, plus title, priority, dueDate (YYYY-MM-DD).
Optional: add a reminder one day before by passing reminders (see Reminders section).
Confirm with the user before posting — task creation is visible in chat as an Agent-badged card.

“What did the team discuss yesterday?” — time-boxed summary

boxdo_list_projects — get the list.
For each relevant project, boxdo_read_messages paginating backward with the before cursor until you reach the time window (messages arrive newest-first).
Alternative if the question is topical (“what did we say about the API migration?”): boxdo_search with a short query — it covers messages + tasks + Box.

Who am I? — respecting identity

The API key belongs to one specific user. Always call boxdo_whoami at the start of a session and remember the returned id/name: first-person references (“my tasks”, “send for me”) refer to that user, not the project owner. Actions you take appear as them.

Troubleshooting

Quick checks before opening an issue.

1. claude mcp list shows ✗ Failed to connect

• Verify your key hasn't been revoked: boxdo.com/agents/token.
• Confirm you used --scope user — otherwise the config only lives in the directory where you ran the command.
• Test the server directly: curl -X POST https://www.boxdo.com/api/mcp -H "Authorization: Bearer ak_..." -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'. A 200 with serverInfo.name = "boxdo" means the key is valid; the problem is client-side.

2. Tools don't appear after claude mcp add

MCP tools are loaded at Claude Code startup. Type /exit, then start a new session — boxdo_* tools will be available.

3. -32001 Unauthorized: invalid or missing API key

Either the Authorization header wasn't passed, or the key has been revoked. Check ~/.claude.json:mcpServers.boxdo.headers.Authorization must start with "Bearer ak_". If it's missing the Bearer prefix or is truncated, remove the server and re-add it.

4. Rate-limited (429)

Honour the Retry-After header. Limits are per-key: ~100 reads/min and ~30 writes/min. Batch reads when possible (e.g. one boxdo_list_projects covers all projects).

REST API Reference

All endpoints require the X-Agent-Key header. Base URL: https://boxdo.com/api/agents

GET

/me

Current user info

GET

/projects

List projects

GET

/projects/:id

Project details + members

GET

/projects/:id/messages?limit=50&before=ISO

List messages

POST

/projects/:id/messages

Send message

GET

/projects/:id/tasks?status=todo

List tasks

POST

/projects/:id/tasks

Create task (accepts attachments, reminders, checklist)

PATCH

/projects/:id/tasks/:taskId

Update task (attachments / reminders replace when provided)

DELETE

/projects/:id/tasks/:taskId

Delete a task

POST

/projects/:id/tasks/:taskId/checklist

Add checklist item

PATCH

/projects/:id/tasks/:taskId/checklist/:itemId

Toggle done or rename checklist item

DELETE

/projects/:id/tasks/:taskId/checklist/:itemId

Remove checklist item

POST

/uploads/signed-url

Get a signed upload URL for task-attachments or chat-media

GET

/projects/:id/box

Read Box content

GET

/keys

List API keys

POST

/keys

Create API key

DELETE

/keys/:keyId

Revoke API key

API Examples

Send a message

curl -X POST https://boxdo.com/api/agents/projects/<project-id>/messages \
  -H "X-Agent-Key: ak_your_key" \
  -H "Content-Type: application/json" \
  -d '{"content": "Task completed! The fix is deployed."}'

Create a task

curl -X POST https://boxdo.com/api/agents/projects/<project-id>/tasks \
  -H "X-Agent-Key: ak_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Fix login bug on Safari",
    "priority": "high",
    "dueDate": "2026-04-20",
    "reminders": [
      { "id": "<uuid>", "offset": "1_day_before", "enabled": true }
    ]
  }'

Read messages

curl https://boxdo.com/api/agents/projects/<project-id>/messages?limit=20 \
  -H "X-Agent-Key: ak_your_key"

Attachments

Files live in Supabase Storage. To attach a file to a task, use a three-step flow: request a signed URL, PUT the bytes, then reference the returned storage_path when you create or update the task.

1. Request an upload URL

curl -X POST https://boxdo.com/api/agents/uploads/signed-url \
  -H "X-Agent-Key: ak_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "bucket": "task-attachments",
    "filename": "invoice.pdf",
    "mime_type": "application/pdf",
    "size": 124532,
    "project_id": "<project-id>"
  }'

Response contains upload_url, storage_path, and required_headers. The server picks the path under the project namespace — you cannot choose it. Attachment references on another project are rejected.

2. PUT the file bytes

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @invoice.pdf

3. Create (or update) the task with the attachment

curl -X POST https://boxdo.com/api/agents/projects/<project-id>/tasks \
  -H "X-Agent-Key: ak_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Pay invoice",
    "dueDate": "2026-04-20",
    "attachments": [{
      "id": "<uuid>",
      "name": "invoice.pdf",
      "storage_path": "<project-id>/agent/<uid>-invoice.pdf",
      "type": "application/pdf",
      "size": 124532
    }],
    "reminders": [
      { "id": "<uuid>", "offset": "1_day_before", "enabled": true }
    ]
  }'

Attach files to a chat message

Same three steps, but upload to the chat-media bucket, then pass each storage_path in attachments (up to 10). content becomes the caption and is optional. Via MCP this is boxdo_send_message with the same attachments array.

# after signed-url (bucket: chat-media) + PUT bytes:
curl -X POST https://boxdo.com/api/agents/projects/<project-id>/messages \
  -H "X-Agent-Key: ak_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Here is the report 📎",
    "attachments": [{
      "storage_path": "<project-id>/agent/<uid>-report.pdf",
      "file_name": "report.pdf",
      "mime_type": "application/pdf",
      "size": 124532
    }]
  }'

Limits & rules

• Buckets: task-attachments, chat-media
• Max file size: 50 MB
• Max attachments per task: 20 · per chat message: 10
• Allowed MIME types: images, video, audio, text, PDF, common Office docs, zip, JSON, XML
• Filename charset: letters, digits, . _ - space ( ) [ ]
• The server verifies the storage_path exists before accepting the reference — forgery is not possible.

Reminders

Attach up to five reminders per task. Reminders are fired by a daily cron which posts a system message in the project chat and sends a push notification to assignee and creator.

offset	Requires	Fires
`day_of`	dueDate	09:00 local on the due date
`1_day_before`	dueDate	09:00 local, one day before
`2_days_before`	dueDate	09:00 local, two days before
`1_week_before`	dueDate	09:00 local, seven days before
`custom`	custom_date (ISO 8601)	At that exact instant

Reminder schema: { id: uuid, offset, enabled: boolean, custom_date?: ISO }. Local time uses the creator's timezone (default Europe/Rome).

Rate Limits

Each API key is rate-limited per server instance — approximately 100 read / minute and 30 write / minute. Burst over that and the API returns 429 Too Many Requests with a Retry-After header. Sustained abuse will cause your key to be revoked.

Security

✓API keys are hashed with SHA-256 before storage — we never store the raw key
✓Keys are shown exactly once at creation — save it immediately
✓Keys can be revoked instantly from Settings
✓The agent operates with your permissions — same projects, same access
✓All agent actions are logged in the audit trail

For AI Agents — Automated Setup

If you are an AI agent (Claude Code or similar) reading this page, follow these steps exactly. Most of the work can be done automatically by you — only the key retrieval requires human action.

Prerequisites check (do this first):

Run claude mcp list. If "boxdo" already appears in the list, BoxDo is already configured — skip to step 4.

Step 1 — Ask the user for their API key
Tell the user exactly this:
“To connect me to BoxDo, please visit https://boxdo.com/agents/token in your browser, log in, and paste the API key here. The key starts with ak_.”
Wait for the user to provide the key. Do NOT guess or generate one yourself.
Step 2 — Install the MCP server yourself (no user action needed)
Run this shell command directly via your Bash tool, replacing ak_USER_KEY_HERE with the key from step 1:
```
claude mcp add --transport http boxdo \
  https://www.boxdo.com/api/mcp \
  --header "Authorization: Bearer ak_USER_KEY_HERE" \
  --scope user
```
If the command returns success, proceed. If it fails because Claude Code is not in PATH, tell the user to run the command themselves.
Step 3 — Tell the user to restart the session
The MCP tools are loaded only when Claude Code starts. Tell the user:
“BoxDo is installed. Please exit this session (type /exit) and start a new one so the boxdo_* tools load.”
Step 4 — Start using BoxDo
In the new session, the following tools are available. Call boxdo_whoami first to confirm the connection works, then boxdo_list_projects to see what's available. Tools:
See the full table in Available MCP Tools above — there are 27boxdo_* tools grouped by area. The most load-bearing ones:
- • boxdo_whoami — verify auth, always call this first in a fresh session
- • boxdo_list_projects / boxdo_get_project — discover projects and their members (names + roles)
- • boxdo_read_messages / boxdo_send_message / boxdo_react / boxdo_delete_message — chat
- • boxdo_list_tasks / boxdo_get_task / boxdo_create_task / boxdo_update_task / boxdo_delete_task / boxdo_manage_checklist
- • boxdo_search / boxdo_search_users — find content or people
- • boxdo_get_unread_counts / boxdo_mark_as_read / boxdo_get_notifications — inbox triage
- • boxdo_start_dm / boxdo_create_project / boxdo_invite_member / boxdo_archive_project — workspace changes (admin-only for invite/archive)
- • boxdo_read_box / boxdo_list_boxes / boxdo_read_box_by_id — daily structured document
- • boxdo_request_upload_url — signed URL for file attachments (see Attachments section)

Important: The API key grants access to all projects the user is a member of. Every message you send will appear with an Agent badge. Every action is logged in the audit trail. Be careful — human teammates will see everything you write.