# agent-hub-mcp

**One place for all your AI sessions.** A tiny personal MCP server that gives your Claude chat, Cowork, Claude Code (and any other MCP client) two shared things:

- **A mailbox between sessions** — one session drops a task into another one's inbox, the other picks it up, does it, and replies. No more copy-pasting between windows.
- **A shared knowledge base** — project status, decisions and notes in one place that every session can read and update.

Runs on Cloudflare Workers + D1. Fits comfortably in the free tier. One account, one hub — your data stays in your own Cloudflare account.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/2tees-cloud/agent-hub-mcp)

> Independent open-source project. Not affiliated with or endorsed by Anthropic.

## Tools

| Tool | What it does |
| --- | --- |
| `hub_send` | Send a message to another session's mailbox (`to`, `from`, `subject`, `body`, optional `thread`) |
| `hub_inbox` | List messages in a mailbox (unread by default) |
| `hub_read` | Read a full message by id (marks it read) |
| `note_put` | Create or overwrite a note (`key` like `projects/my-app/status`, `content`, `tags`) |
| `note_get` | Read a note by key |
| `note_search` | Search notes by words in key, text or tags (any language) |
| `note_list` | List notes, optionally by key prefix |
| `note_delete` | Delete a note |

Mailbox names are free-form: `cowork`, `code`, `chat`, or per project (`code-my-repo`).

## Install

### Option A — one click

1. Click **Deploy to Cloudflare** above. Cloudflare copies the repo to your GitHub, creates the D1 database and deploys the Worker.
2. When asked for `HUB_SECRET`, paste a long random string (at least 24 characters), e.g. from `openssl rand -base64 32 | tr -d '/+='`.
3. Your MCP URL is `https://agent-hub.<your-subdomain>.workers.dev/mcp/<HUB_SECRET>`.

### Option B — command line

Requires Node.js 18+.

```bash
git clone https://github.com/2tees-cloud/agent-hub-mcp.git
cd agent-hub-mcp
npm install
npx wrangler login
npm run deploy
```

`npm run deploy` creates (or reuses) the D1 database, deploys the Worker, generates the secret and prints your MCP URL. It is also saved to `.hub-url`.

**The URL is your access key. Keep it private.** If it leaks: delete `.hub-secret` and run `npm run deploy` again — you get a new URL.

## Connect your clients

**Claude (web/desktop) and Cowork** — once per account:
Customize → Connectors → **+ Add** → **Add custom connector** → name `agent-hub`, URL = your MCP URL → Authentication: **No sign in** → **Add**.

**Claude Code on your computer:**

```bash
claude mcp add --transport http agent-hub --scope user "<your MCP URL>"
```

**Claude Code in the cloud (sessions on a repository):** add an environment variable `AGENT_HUB_URL` = your MCP URL in the cloud environment settings, and commit this `.mcp.json` to the repo root (the URL itself never lands in git):

```json
{
  "mcpServers": {
    "agent-hub": { "type": "http", "url": "${AGENT_HUB_URL}" }
  }
}
```

## Use it

- In Cowork: *"send to code: run the tests on branch X and report back"* → goes to the `code` mailbox.
- In Claude Code: *"check the code mailbox and do the new tasks"*, or keep it working on its own: `/loop 5m check the code mailbox and do new tasks, reply to cowork`.
- In Cowork: *"anything from code?"* → reads the `cowork` mailbox.
- Anywhere: *"save the project status to the hub"*, *"what does the hub say about project X?"*.

## Teach your agents the protocol (optional)

`skill/agent-hub/SKILL.md` is a ready-made skill that tells Claude how to hand off tasks, reply and keep shared notes. Add it to Claude (Customize → Skills → upload) and/or copy it into a repository as `.claude/skills/agent-hub/SKILL.md` for Claude Code.

## Security notes

- Access is a secret in the URL path. Anyone with the URL can read and write your hub — treat it like a password.
- Never put API keys, tokens, passwords or `.env` contents into messages or notes.
- Messages and notes are limited to 200,000 characters each.
- Your data lives in your own D1 database; you can browse or export it in the Cloudflare dashboard.

## Local development

```bash
cp .dev.vars.example .dev.vars   # then set HUB_SECRET
npm run dev                      # http://localhost:8787/mcp/<HUB_SECRET>
```

## License

MIT

---

## Коротко по-русски

Личный MCP-центр: почтовый ящик между сессиями AI (Claude, Cowork, Claude Code и другие MCP-клиенты) и общая база заметок. Установка: кнопка **Deploy to Cloudflare** выше или `npm install && npx wrangler login && npm run deploy`. Полученный адрес добавь в Claude как custom connector («No sign in») и в Claude Code командой `claude mcp add --transport http agent-hub --scope user "<адрес>"`. Адрес — это ключ доступа, никому его не показывай.