# Connect to Buildiary

This page is for AI agents. A person asked you to connect to Buildiary (https://buildiary.vercel.app), a private diary of their projects that you'll keep up to date as you work together. If you're a person reading this, go to https://buildiary.vercel.app/connect instead.

Before you change anything, tell the person in one sentence what you're about to do. Never ask them for a password, key or token. Keep your messages short and plain: many people setting this up don't use a terminal or edit config files, so do those parts yourself whenever you can.

## 1. Already connected?

If you already have Buildiary tools (try `get_account`), call it, tell the person its message, and go to "Once connected".

## 2. Connect, using the first route that fits you

### A. You can change your own MCP settings

Coding agents such as Claude Code, Cursor, VS Code with Copilot, Codex (app, CLI or IDE), Gemini CLI and Zed. Add a remote MCP server named "buildiary" at https://buildiary.vercel.app/mcp. Sign-in opens in the browser. Keep the person's other settings and show them what you changed.

- Claude Code: run `claude mcp add --transport http --scope user buildiary https://buildiary.vercel.app/mcp`
- Cursor: add `"buildiary": { "url": "https://buildiary.vercel.app/mcp" }` under `mcpServers` in ~/.cursor/mcp.json
- VS Code (Copilot): add `"buildiary": { "type": "http", "url": "https://buildiary.vercel.app/mcp" }` under `servers` in .vscode/mcp.json
- Codex (the app, CLI and IDE extension share one config): run `codex mcp add buildiary --url https://buildiary.vercel.app/mcp`, or add `[mcp_servers.buildiary]` with `url = "https://buildiary.vercel.app/mcp"` to ~/.codex/config.toml
- Gemini CLI: add `"buildiary": { "type": "http", "url": "https://buildiary.vercel.app/mcp" }` under `mcpServers` in ~/.gemini/settings.json
- Anything else: use your own way of adding a remote HTTP MCP server with OAuth.

Then tell the person the one thing left to do, in plain words and in terms of your own app: whether they need to reload or restart you, and exactly where to click to sign in. For example: in Claude Code type /mcp, choose buildiary and select Authenticate; in Cursor open Settings → MCP and click the sign-in button next to buildiary; in the Codex app open Settings → MCP servers and click Authenticate (in a terminal you can run `codex mcp login buildiary` for them). They approve access in the browser with their Buildiary account. Tell them that afterwards the browser may show a plain "Authenticated" page on localhost, which is normal and can be closed. Ask them to tell you when they're done, then continue with "Once connected".

### B. You use skills and can make web requests yourself

For example OpenClaw or Hermes Agent. Read the Buildiary skill at https://buildiary.vercel.app/skills/buildiary/SKILL.md and follow its sign-in steps. The person approves sign-in with a short code.

### C. You're a chat app that can't change its own settings

For example the Claude app or ChatGPT. Walk the person through adding Buildiary as a connector, one step at a time, waiting for them after each step. The address to paste is https://buildiary.vercel.app/mcp.

- Claude: Customize → Connectors → + → Add custom connector. Paste the address, connect, and approve access. Then choose Buildiary from the chat tools menu.
- ChatGPT web: Settings → Security and login → Developer mode. Then go to https://chatgpt.com/plugins and select +. Enter Buildiary as the name, paste the address under Connection, choose OAuth, create the connection, and approve access. Start a new chat, choose Developer mode from the + menu, and select Buildiary. Developer mode supports reading and writing on Plus, Pro, Business, Enterprise and Education accounts on the web; availability depends on account and workspace settings. A workspace admin may need to enable it.

Menus change. If what they see doesn't match, help them find the equivalent rather than giving up.

### D. None of these fit

Tell the person you can't connect to Buildiary directly and send them to https://buildiary.vercel.app/connect.

## Once connected

1. Call `get_account` (or `GET /v1/me` through the skill) and tell the person its message, for example "Connected to Buildiary as @name". If it warns that the account has no username, show the warning and stop: don't create or change anything until they reply. It usually means they signed in with a different login than they use on the website.
2. If you're working in a code repository, find its project in Buildiary by matching the exact repository URL first, then the exact project name. Ask which project to track if the match is ambiguous. If none exists, create one with a name, a one-line description, a stage and a next step, then add a short update about where things stand.
3. After substantial requested work is completed on that project (a feature, resolved bug or milestone), add one concise progress update before your final response without asking for separate approval. Skip small tweaks, plans, investigations and incomplete work. Read the current project first; keep the stage and next step current only when they changed. When the work is visible, attach a screenshot: upload it with `get_image_upload_url` (or `POST /v1/uploads` through the skill) and pass the storage ID in the update's images.
4. Everything is private. Don't make anything public unless the person asks.

## If something goes wrong

- Buildiary tools don't appear after signing in: start a new chat, or restart the app fully.
- Calls are refused with agent_access_disabled: the person turned off Agent access; ask them to turn it back on in their Buildiary workspace.
- More help for the person: https://buildiary.vercel.app/connect