@channlize/mcp 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # @channlize/mcp
 
+## 0.6.0
+
+### Minor Changes
+
+- b9bdf13: Channlize for Agents, Phase 4: deeper observability.
+
+  `@channlize/core`: the agents client gets `insights.graph`, `insights.edge` (and the `insights.edgeAll` iterator), `insights.cost({ groupBy })` and `insights.metrics`; `search(...)` and the `searchAll` iterator; with an unbound `agents:admin` key, `exports.download(kind, format, filters)` (returns the body with `rows` and `truncated`), `exports.start`, `exports.get` and `exports.list`, and `telemetry.getOtel` / `setOtel` / `testOtel` / `getWebhook` / `setWebhook` / `testWebhook`. Typed DTOs mirror the API responses, including `range`. `verifyTelemetryWebhook` and `parseTelemetryWebhook` check telemetry webhook batches (`sha256=<hex HMAC-SHA256 of the raw body>`, the same scheme as agent webhooks; Node.js 18 compatible).
+
+  `@channlize/mcp`: new read-only agent tools (`agents:read`): `search_agent_messages`, `get_agent_graph`, `get_agent_cost` and `get_agent_metrics`. The insights tools return the top rows, totals and a one-line summary, and `mine: true` keeps the server's own agent. A `CHANNEL_NOT_VISIBLE` error now tells the model how to fix it. There are no export or telemetry tools: they stay with an `agents:admin` key in `@channlize/core` or the dashboard.
+
+  `@channlize/skills`: `channlize-agents` covers searching history, checking cost and latency, exports and OpenTelemetry; `channlize-mcp-setup` lists the new tools.
+
+### Patch Changes
+
+- Updated dependencies [b9bdf13]
+  - @channlize/core@0.6.0
+
+## 0.5.0
+
+### Minor Changes
+
+- b9d54a0: Channlize for Agents: your own AI agents talk to other agents and to people in agent channels.
+
+  `@channlize/core` adds `createAgentsClient()` (also `ChannlizeClient.agents`): `send` (messages, tasks and task status), `inbox` and `ack`, `poll` (a loop that acks each message once its handler resolves and backs off on errors), `list` / `get` for the agent directory, and `channels.list` / `get` / `members` / `messages`. `verifyAgentWebhook()` and `parseAgentWebhook()` check the `X-Webhook-Signature` of a webhook agent delivery. Typed DTOs (`Agent`, `AgentChannel`, `AgentMessage`, `AgentInboxItem`, `AgentWebhookPayload`, …) mirror the API. `readChannlizeEnv()` reads `CHANNLIZE_AGENT_ID`.
+
+  `@channlize/mcp` adds the agent tools `send_agent_message`, `create_task`, `update_task_status`, `read_agent_inbox`, `ack_agent_messages`, `list_agents` and `list_agent_channels` (scopes `agents:send` / `agents:read`), importable without the server from `@channlize/mcp/agents`. `CHANNLIZE_AGENT_ID` / `--agent-id` (config `agentId`) sets the default agent for multi-agent keys.
+
+  `@channlize/skills` adds the `channlize-agents` skill, and the MCP setup skill lists the agent tools.
+
+  These call the `/v1/agents` API (Channlize/api#152): publish only once it is live in production.
+
+- 7815276: Channlize for Agents, Phases 2 and 3: agents ask humans and wait for the answer, work on tasks, and respect policies and human takeovers.
+
+  `@channlize/core`: the agents client adds `ask`, `askAndWait` (loops the 25 s long-poll until the question is answered, expired or canceled, or the overall timeout) and `questions.get` / `list` / `wait` / `answer` / `cancel`; `tasks.create` / `list` / `board` / `get` / `update` / `handoff`; and, for an unbound `agents:admin` key, `teams.*`, `policies.*` (with `preview`), `orgChart.get` / `setManager` / `setOwner`, `onboarding` and `setStatus`. New typed errors: `AgentPolicyError` (the `POLICY_*` codes, with `retryAt`), `HumanTakeoverError`, `AgentThreadPausedError` (with `reason`; still a `RateLimitError`), `AgentTaskError` and `QuestionClosedError`, plus `isRetryable(err)` and `retryAfter(err)`. Every `ChannlizeError` now carries `retryAt` when the API sends one (or a `Retry-After` header), network errors have the code `NETWORK_ERROR`, and 429 `AGENT_RATE_LIMITED` keeps its code. `parseAgentWebhookEvent` and the guards `isAgentMessageWebhook`, `isQuestionOutcomeWebhook`, `isQuestionEscalatedWebhook`, `isQuestionOutcomeMessage` and `isTaskHandoffMessage` cover the question and handoff deliveries. `AgentMessageSender` gains the `slack_user` kind.
+
+  `@channlize/mcp`: new agent tools `ask_human`, `get_answer` (waits up to 25 s and says "still waiting" otherwise), `list_questions`, `cancel_question`, `answer_escalated_question`, `update_task`, `handoff_task`, `list_tasks`, `get_task_board`, `get_org_chart` and the read-only `get_effective_policy` (`agents:admin`). `create_task` now uses `POST /v1/agents/tasks` and takes `assigneeAgentId` and `dueAt` (it returns `task` besides `taskId` and `message`; `tokens` and `cost` are no longer accepted). Error hints cover the policy, takeover, task and question codes, and say when to retry. There are no tools that write policies, teams or the org chart.
+
+  `@channlize/skills`: the `channlize-agents` skill covers asking humans, approvals, tasks and handoffs, policy back-off and human takeovers; the MCP setup skill lists the new tools.
+
+  These call the Phase 2 and 3 `/v1/agents` APIs (Channlize/api#149, #150).
+
+- 75da9d3: `@channlize/mcp` can now work the inbox: `list_conversations` (filters for status, priority, assignee, project, tag, source, `updatedSince` and AI triage intent/urgency, paginated), `search_conversations`, `get_conversation` (internal notes flagged), `reply_to_conversation`, `add_internal_note`, `assign_conversation`, `tag_conversation`, `close_conversation`, `reopen_conversation`, `get_analytics_summary`, and `list_routing_rules` / `create_routing_rule` / `update_routing_rule` / `delete_routing_rule`. They call the new scoped `/v1` API-key endpoints (`inbox:read`, `inbox:write`, `routing:write`, `analytics:read`) and act as a named agent: replies show in Slack as "Replied by <key name> (agent)".
+
+  `list_conversations` and `get_conversation` now use `/v1/conversations`: the list is filtered and paginated on the server (`total`, `hasMore`) instead of scanning the latest 50, and rows carry `customer` and `assignee` objects. A `read` key still works.
+
+  The inbox tool definitions are importable without the MCP server from `@channlize/mcp/inbox` (`INBOX_TOOLS`, `runInboxTool`, `inboxToolsAsJsonSchema`), for other agents and bots. The triage and MCP setup skills describe the new tools and scopes.
+
+### Patch Changes
+
+- Updated dependencies [b9d54a0]
+- Updated dependencies [7815276]
+  - @channlize/core@0.5.0
+
 ## 0.4.0
 
 ### Minor Changes

package/README.md

@@ -1,6 +1,6 @@
 # @channlize/mcp
 
-[Model Context Protocol](https://modelcontextprotocol.io) server for [Channlize](https://channlize.com). It lets an AI assistant (Claude, Cursor, VS Code Copilot, Windsurf…) read your support inbox, contacts, logs and Events, and send Events to Slack.
+[Model Context Protocol](https://modelcontextprotocol.io) server for [Channlize](https://channlize.com). It lets an AI assistant (Claude, Cursor, VS Code Copilot, Windsurf, or your own bot) work your support inbox: list, search and read conversations, reply to customers, add internal notes, assign, tag, close and reopen, manage routing rules and read analytics. It also reads contacts, logs and Events, sends Events to Slack, and lets your own agents talk to other agents and to people (Channlize for Agents).
 
 - Built on the official MCP TypeScript SDK v2 (`@modelcontextprotocol/server` 2.4), which implements the 2026-07-28 spec revision and still negotiates 2025-11-25 and earlier with older clients.
 - Transports: **stdio** (default) and **Streamable HTTP** (`--transport http`). The deprecated HTTP+SSE transport isn't offered.
@@ -10,15 +10,33 @@
 
 | Key | Where | Enables |
 | --- | --- | --- |
-| Server API key `ch_live_…` (secret) | `CHANNLIZE_SERVER_API_KEY` | Inbox, contacts, Events and log tools. `read` scope for the read tools, `write` scope to send Events and logs and open conversations or contacts. |
+| Server API key `ch_live_…` (secret) | `CHANNLIZE_SERVER_API_KEY` | Inbox, routing, analytics, contacts, Events and log tools, as its scopes allow (below). An agent key or a multi-agent key enables the agent tools. |
 | Widget key `wk_…` (public, optional) | `CHANNLIZE_WIDGET_KEY` | Visitor-side tools (contact form, chat session), for testing your setup. |
 
-Create both in the dashboard under **SDK & Integration → API keys**. A read-only key is enough to explore and triage; use a `write` key only if the assistant should post to Slack.
+Create both in the dashboard under **SDK & Integration → API keys**, and pick the scopes there:
+
+| Scope | Grants |
+| --- | --- |
+| `read` | The read tools: conversations, contacts, routing rules, logs, Events, analytics |
+| `write` | `notify_event`, `track_log`, `create_conversation`, `create_contact` |
+| `inbox:read` | `list_conversations`, `search_conversations`, `get_conversation`, `list_routing_rules` |
+| `inbox:write` | `reply_to_conversation`, `add_internal_note`, `assign_conversation`, `tag_conversation`, `close_conversation`, `reopen_conversation` |
+| `routing:write` | `create_routing_rule`, `update_routing_rule`, `delete_routing_rule` (and `list_routing_rules`) |
+| `analytics:read` | `get_analytics_summary` |
+| `agents:send` | `send_agent_message`, `create_task`, `update_task`, `update_task_status`, `handoff_task`, `answer_escalated_question` |
+| `agents:read` | `read_agent_inbox`, `ack_agent_messages`, `list_agents`, `list_agent_channels`, `list_tasks`, `get_task_board`, `get_org_chart`, `list_questions` (and `get_answer`), `search_agent_messages`, `get_agent_graph`, `get_agent_cost`, `get_agent_metrics` |
+| `agents:ask_human` | `ask_human`, `get_answer`, `cancel_question` |
+| `agents:admin` (unbound key) | `get_effective_policy` (read-only) |
+
+A `read` key is enough to explore and triage. A plain `write` key can't reply or change routing: those need `inbox:write` or `routing:write`. Keys created before scopes existed keep working as they did.
+
+The inbox tools act as a named agent, the key's name: a reply shows in Slack as "Replied by Support bot (agent)" and changes as "Status changed to closed by Support bot (agent)". Name the key after the assistant, and use one key per assistant so you can tell them apart and revoke one.
 
 Other settings:
 
 - `CHANNLIZE_PROJECT_ID`: the project for Events and logs. It defaults to the first project of the key's organization.
 - `CHANNLIZE_API_KEY`: either kind of key, detected by its prefix.
+- `CHANNLIZE_AGENT_ID`: the agent the agent tools act as when a call doesn't pass `agentId`. Set it with a multi-agent key; an agent key always acts as its own agent.
 - `CHANNLIZE_BASE_URL`: default `https://api.channlize.com`.
 - `CHANNLIZE_TIMEOUT`: in ms, default 10000.
 
@@ -110,14 +128,94 @@ It binds to `127.0.0.1` by default and rejects requests whose `Host` or `Origin`
 
 ## Tools
 
-Server API key:
+### Inbox (server API key, agent scopes)
+
+| Tool | Scope | Endpoint | What it does |
+| --- | --- | --- | --- |
+| `list_conversations` | `inbox:read` | `GET /v1/conversations` | Conversations by last activity, filtered by status, priority, assignee (ID, email, `unassigned`, `assigned`), project, tag, source, `updatedSince` and AI triage `intent` / `urgency`. Paginated. |
+| `search_conversations` | `inbox:read` | `GET /v1/conversations?q=` | Same, matching the subject, customer name or email, or any message's text |
+| `get_conversation` | `inbox:read` | `GET /v1/conversations/:id` | The full thread, internal notes flagged `isInternal`, plus assignee, customer, triage and Slack thread |
+| `reply_to_conversation` | `inbox:write` | `POST /v1/conversations/:id/reply` | Reply to the customer as the key; delivered like a dashboard reply (widget, email, SMS…) and mirrored to the Slack thread. `open` becomes `pending`. |
+| `add_internal_note` | `inbox:write` | `POST /v1/conversations/:id/notes` | A note in the Slack thread and the conversation; never sent to the customer |
+| `assign_conversation` | `inbox:write` | `PATCH /v1/conversations/:id` | Assign to a teammate by user ID or email, or unassign with `null`; the teammate is notified |
+| `tag_conversation` | `inbox:write` | `PATCH /v1/conversations/:id` | `add`, `remove`, or `set` (replace) tags |
+| `close_conversation` | `inbox:write` | `PATCH /v1/conversations/:id` | Status `closed` (or `resolved`); nothing is sent to the customer |
+| `reopen_conversation` | `inbox:write` | `PATCH /v1/conversations/:id` | Status `open` |
+| `get_analytics_summary` | `analytics:read` | `GET /v1/analytics/summary` | KPIs for a period with the previous one, and the inbox now (open, pending, unassigned, urgent, awaiting reply) |
+| `list_routing_rules` | `routing:write`, `inbox:read` or `read` | `GET /v1/routing-rules` | Rules in evaluation order |
+| `create_routing_rule` | `routing:write` | `POST /v1/routing-rules` | Send new conversations matching `conditions` to a Slack channel, optionally assigning them |
+| `update_routing_rule` | `routing:write` | `PATCH /v1/routing-rules/:id` | Change a rule; omitted fields keep their value (`isActive: false` pauses it) |
+| `delete_routing_rule` | `routing:write` | `DELETE /v1/routing-rules/:id` | Delete a rule |
+
+Status changes, assignments and tags are recorded in the conversation's timeline, posted in its Slack thread, and the Slack root post is refreshed. Every inbox tool is listed for a server key; a call the key's scopes don't allow returns an error naming the scope to add.
+
+A routing rule's `conditions` is a group: `{ "match": "all" | "any", "conditions": [{ "field", "operator", "value" }] }`, tested on a new conversation's first message. Fields: `source`, `project`, `widget`, `connection`, `page_url`, `page_domain`, `customer_email`, `customer_email_domain`, `message`, `subject`, `tags`, `priority`, `language`. Operators: `equals`, `not_equals`, `contains`, `not_contains`, `starts_with`, `ends_with`, `matches` (`*` / `?` wildcards). `value` is a string or a list; an empty `conditions` list catches everything.
+
+### Channlize for Agents
+
+Your agent talks to other agents and to people in agent channels, asks people when it needs a decision, and works on tasks. Create the agent, its channels and an **agent key** (or a **multi-agent key**, which acts as several agents) in the dashboard under **Agents**, with the `agents:send` and `agents:read` scopes, plus `agents:ask_human` to ask people. Then run the server as that agent:
+
+```bash
+claude mcp add channlize-reviewer \
+  --env CHANNLIZE_SERVER_API_KEY=ch_live_… \
+  --env CHANNLIZE_AGENT_ID=<agent id> \
+  -- npx -y @channlize/mcp
+```
+
+| Tool | Scope | Endpoint | What it does |
+| --- | --- | --- | --- |
+| `send_agent_message` | `agents:send` | `POST /v1/agents/messages` | Post to a channel (or a thread, with `threadId`), mentioning agents. Delivered to the channel's other agents and mirrored to Slack. One Event per message. |
+| `read_agent_inbox` | `agents:read` | `GET /v1/agents/:id/inbox` | Unacknowledged messages, oldest first, with `nextCursor` |
+| `ack_agent_messages` | `agents:read` | `POST /v1/agents/:id/inbox/ack` | Acknowledge what you handled (`upTo` or `ids`) so it leaves the inbox |
+| `list_agents` | `agents:read` | `GET /v1/agents` | The organization's agents, for `mentions` and `agentId` |
+| `list_agent_channels` | `agents:read` | `GET /v1/agents/channels` | The channels your key's agents are members or observers of |
+| `get_org_chart` | `agents:read` | `GET /v1/agents/org-chart` | Agents with their manager, owner and teams, and the reporting tree |
+
+Tasks:
+
+| Tool | Scope | Endpoint | What it does |
+| --- | --- | --- | --- |
+| `create_task` | `agents:send` | `POST /v1/agents/tasks` | Create a task (board status `open`) in its own thread, optionally with an assignee (`assigneeAgentId`, a channel member) and a due date. Returns `taskId` and `task`. |
+| `update_task` | `agents:send` | `PATCH /v1/agents/tasks/:taskId` | Move it on the board (`open`, `in_progress`, `blocked`, `done`, `failed`) and/or change the due date, with a note. Assignee or creator only. |
+| `update_task_status` | `agents:send` | `POST /v1/agents/messages` | Report `working`, `input_required`, `completed`, `failed`, `canceled` or `rejected`, with a note and result data. The last four are final. |
+| `handoff_task` | `agents:send` | `POST /v1/agents/tasks/:taskId/handoff` | Hand the task to another member agent of its channel, with a reason |
+| `list_tasks` | `agents:read` | `GET /v1/agents/tasks` | A channel's tasks, by assignee or status |
+| `get_task_board` | `agents:read` | `GET /v1/agents/tasks/board` | A channel's board: tasks by column, counts, agents |
+
+Humans in the loop:
+
+| Tool | Scope | Endpoint | What it does |
+| --- | --- | --- | --- |
+| `ask_human` | `agents:ask_human` | `POST /v1/agents/questions` | Ask people a question (options, free text) or for an approval (Approve / Deny, with an amount, a resource and required roles). Posted in Slack, escalated until answered or the deadline. Returns `questionId` at once. One Event. |
+| `get_answer` | `agents:ask_human` or `agents:read` | `GET /v1/agents/questions/:id/wait` | Waits up to 25 s (`waitSeconds`) for the answer. `waiting: true` with a "still waiting" message when nobody has answered yet: call it again. |
+| `list_questions` | `agents:read` | `GET /v1/agents/questions` | Your questions and those escalated to you, by status |
+| `cancel_question` | `agents:ask_human` | `DELETE /v1/agents/questions/:id` | Withdraw one of your open questions |
+| `answer_escalated_question` | `agents:send` | `POST /v1/agents/questions/:id/answer` | As the asker's manager agent, answer a question escalated to you. The first answer wins. |
+| `get_effective_policy` | `agents:admin` | `GET /v1/agents/policies/preview` | The policy in force for an agent (in a channel): rules, who set them, usage, working hours, and whether it may post and read now. Needs an unbound admin key. |
+
+History and numbers (read-only):
+
+| Tool | Scope | Endpoint | What it does |
+| --- | --- | --- | --- |
+| `search_agent_messages` | `agents:read` | `GET /v1/agents/search` | Full-text search over messages, tasks, status updates and questions (with their answers), best match first. `q` takes `"exact phrase"`, `or`, `-word`; ids match as substrings. Each result has a highlight (hits in `**bold**`), the channel, `threadId` and a Slack link. Paged with `cursor`. |
+| `get_agent_cost` | `agents:read` | `GET /v1/agents/insights/cost` | Reported spend over a range of UTC days: totals, the top groups by `agent`, `channel`, `team`, `task` or `day` with their share, the active days and the peak day |
+| `get_agent_metrics` | `agents:read` | `GET /v1/agents/insights/metrics` | Reply latency (avg, p50, p90) between agents and people, the time to a human answer, delivery failure and retry rates, and the inbox backlog right now |
+| `get_agent_graph` | `agents:read` | `GET /v1/agents/insights/graph` | Who talks to whom: the busiest participants and sender → recipient edges, with reply latency |
+
+The insights tools return the `top` rows (default 10, 5 for metrics, at most 50), the totals, what was left out (`omitted`) and a one-line `summary`, rather than the whole graph or series, so the answer fits in a few hundred tokens. `from` / `to` are `YYYY-MM-DD`, by default the last 30 days, clamped to the plan's history window (`range.clamped`). `mine: true` keeps your own agent (`CHANNLIZE_AGENT_ID`), and `agentId` picks another. They only see what the key may read: a key bound to agents sees the channels its agents can read, and an unbound `agents:admin` key sees the org. For the full responses, use [`@channlize/core`](https://github.com/channlize/sdk/tree/main/packages/core#search-cost-and-latency) (`agents.search`, `agents.insights.*`).
+
+Every other agent tool takes an optional `agentId`; it defaults to `CHANNLIZE_AGENT_ID` (`--agent-id`). Only channel members can post; observers can only read. Errors name the fix: a missing scope, an agent the key can't act as, a channel the agent isn't a member of, a thread the loop guard paused. Policy refusals say whether to wait (`POLICY_RATE_LIMITED`, `POLICY_BUDGET_EXHAUSTED` and `POLICY_OUTSIDE_WORKING_HOURS` carry the time to retry after) or not to retry at all (a channel, DM or urgency the policy forbids). `HUMAN_TAKEOVER` means a person took the thread over: the agent stays out until the time it gives.
+
+There are no tools that write policies, teams, the org chart or an agent's status. Those are the guardrails on what an agent may do, so the agent shouldn't hold the pen: change them in the dashboard, or in code with an `agents:admin` key and the [`@channlize/core` agents client](https://github.com/channlize/sdk/tree/main/packages/core#channlize-for-agents) (`agents.policies`, `agents.teams`, `agents.orgChart`, `agents.setStatus`). For a webhook or polling agent in code, see the same client.
+
+There are no export or telemetry tools either. An export dumps the org's whole history (messages, tasks, questions, the audit log), and the telemetry settings decide where every agent's traces are sent, with the collector's credentials. Both need an unbound `agents:admin` key and belong to the people who run Channlize. Use the dashboard, or [`agents.exports` and `agents.telemetry`](https://github.com/channlize/sdk/tree/main/packages/core#exports-and-opentelemetry-admin) in `@channlize/core`. An agent reads its own history with `search_agent_messages`.
+
+### Contacts, Events and logs (server API key)
 
 | Tool | Scope | What it does |
 | --- | --- | --- |
 | `get_project` | any | Project name and ID, totals, the key's permissions, Slack connection |
 | `get_analytics` | any | Daily conversations and messages for the last 30 days |
-| `list_conversations` | read | Recent conversations, filtered by status or priority |
-| `get_conversation` | read | One conversation with its message thread |
 | `create_conversation` | write | Open a conversation for a customer (posted to Slack) |
 | `list_contacts` | read | Customers, paginated |
 | `get_contact` | read | One customer |
@@ -128,11 +226,11 @@ Server API key:
 | `query_logs` | read | Search log tracking by severity, source, text and time |
 | `track_log` | write | Record a log line |
 
-Widget key (visitor side): `submit_contact_form`, `create_chat_session`, `send_message`, `get_chat_messages` and `close_chat_session`.
+### Widget key (visitor side)
 
-Each tool declares input and output schemas and annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`), and returns `structuredContent`. Errors come back as tool errors that say how to fix them, such as a missing scope, a revoked key or an unknown ID.
+`submit_contact_form`, `create_chat_session`, `send_message`, `get_chat_messages` and `close_chat_session`.
 
-You can't reply to a conversation or change its status or priority through the API yet. The team does that in the Slack thread or the dashboard.
+Each tool declares input and output schemas and annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`), and returns `structuredContent`. Errors come back as tool errors that say how to fix them, such as a missing scope, a revoked key or an unknown ID. Most clients ask before running a tool that isn't read-only; keep that on for `reply_to_conversation`, which reaches the customer.
 
 ## Resources and prompts
 
@@ -145,7 +243,7 @@ Resources:
 
 Prompts:
 
-- `triage-conversations`: rank open conversations and draft replies.
+- `triage-conversations`: rank open conversations and draft replies (sent only if you confirm, with `inbox:write`).
 - `summarize-conversation`
 - `check-events`: explain skipped or failed deliveries.
 - `setup-events`, `setup-live-chat`, `integrate-contact-form`: add Channlize to the codebase you're working in.
@@ -155,7 +253,8 @@ Prompts:
 - **"A Channlize key is required"**: set `CHANNLIZE_SERVER_API_KEY` in the client's `env` block, then restart the client.
 - **"holds a widget key (wk_…)"**: you passed the public widget key as the server key. Create a server API key, or pass the widget key as `CHANNLIZE_WIDGET_KEY`.
 - **401 invalid key**: the key was revoked, has expired or was mistyped. Create a new one.
-- **403 lacks required permission**: the key is read-only. Create a key with the `write` scope for `notify_event`, `track_log`, `create_conversation` and `create_contact`.
+- **403 lacks required permission**: the key is missing the scope the error names. `write` covers `notify_event`, `track_log`, `create_conversation` and `create_contact`; the inbox writes need `inbox:write` and routing changes `routing:write`. Scopes are fixed at creation, so create a new key.
+- **"Pass agentId" / "agent_id is required with a multi-agent key"**: set `CHANNLIZE_AGENT_ID` (`--agent-id`) to the agent's ID, or pass `agentId` on the call.
 - **404 project not found**: `CHANNLIZE_PROJECT_ID` is wrong, or belongs to another organization.
 - **The server doesn't start**: check `node --version` (20+) and run `npx -y @channlize/mcp --help`. To inspect the server interactively, run `npx @modelcontextprotocol/inspector npx -y @channlize/mcp`.
 
@@ -173,6 +272,52 @@ await server.runStdio(); // or: await server.runHttp({ port: 3333 })
 const mcp = buildServer({ serverApiKey: '…' });
 ```
 
+### Inbox tools without the MCP server
+
+`@channlize/mcp/inbox` holds the inbox tool definitions (name, title, description, scope, endpoint, zod input and output schemas, annotations, handler) and doesn't load the MCP server or its transports. Use it to give the same tools to another agent, such as an LLM function-calling loop or an internal bot:
+
+```ts
+import {
+  INBOX_TOOLS,
+  inboxToolsAsJsonSchema,
+  runInboxTool,
+} from '@channlize/mcp/inbox';
+import { ChannlizeApi, resolveConfig } from '@channlize/mcp';
+
+const api = new ChannlizeApi(
+  resolveConfig({ serverApiKey: process.env.CHANNLIZE_SERVER_API_KEY })
+);
+
+// JSON Schema definitions ({ name, description, parameters }) for an LLM API.
+const tools = inboxToolsAsJsonSchema(t => t.scope !== 'routing:write');
+
+// Run the tool the model picked: arguments are validated with its zod schema.
+const result = await runInboxTool(api, 'list_conversations', {
+  status: ['open'],
+  assignee: 'unassigned',
+});
+```
+
+### Agent tools without the MCP server
+
+`@channlize/mcp/agents` does the same for the agent tools: `AGENT_TOOLS`, `runAgentTool`, `agentToolsAsJsonSchema`. The requester may carry a default `agentId`:
+
+```ts
+import { agentToolsAsJsonSchema, runAgentTool } from '@channlize/mcp/agents';
+import { ChannlizeApi, resolveConfig } from '@channlize/mcp';
+
+const api = new ChannlizeApi(
+  resolveConfig({
+    serverApiKey: process.env.CHANNLIZE_SERVER_API_KEY,
+    agentId: process.env.CHANNLIZE_AGENT_ID,
+  })
+);
+const tools = agentToolsAsJsonSchema();
+const inbox = await runAgentTool(api, 'read_agent_inbox', { limit: 10 });
+```
+
+A handler only needs an object with `request(method, path, { query, body, timeout })` (`get_answer` passes a longer `timeout`, in ms, for its long-poll), so you can pass your own client (for example one that adds logging or calls the API in-process). Failures throw `ToolError` with a message written for the model.
+
 ## Documentation
 
 - Guide: https://channlize.com/docs/mcp

package/dist/agents.d.mts

@@ -0,0 +1,94 @@
+import * as z from 'zod/v4';
+import { ToolAnnotations, HttpMethod } from './inbox.mjs';
+import '@channlize/core';
+
+/**
+ * The Channlize for Agents toolset: names, zod input/output schemas and
+ * handlers for talking to other agents and to people in agent channels,
+ * through `/v1/agents`.
+ *
+ * Like `inbox.ts`, it has no dependency on the MCP server or its
+ * transports, so any agent can import it (`@channlize/mcp/agents`): the
+ * stdio/HTTP server registers these tools (`registerAgentTools` in
+ * `tools.ts`), and an LLM loop can run the same handlers with its own client
+ * (anything with a `request(method, path, { query, body })`).
+ *
+ * Identity: the key decides who the tools act as. An agent key acts as its
+ * agent; a multi-agent key acts as one of its agents, picked by `agentId`
+ * on the call or the requester's default `agentId` (`CHANNLIZE_AGENT_ID` /
+ * `--agent-id` on the server).
+ *
+ * Scopes: `agents:send` (post messages, create, update and hand off
+ * tasks, answer escalated questions), `agents:read` (directory, channels,
+ * inbox and ack, tasks, the org chart, search, and the graph, cost and
+ * metrics insights), `agents:ask_human` (ask people and read the answer)
+ * and `agents:admin` (`get_effective_policy` only).
+ *
+ * No admin-write tools: changing policies, teams, the org chart or an
+ * agent's status stays in the dashboard or `@channlize/core` with an
+ * `agents:admin` key. Policies are the guardrails on what an agent may do,
+ * so the agent that runs these tools shouldn't be able to rewrite them.
+ *
+ * No export or telemetry tools either (Phase 4): exports dump the org's
+ * whole history (messages, tasks, questions, the audit log), and the
+ * telemetry settings choose where every agent's traces go, with
+ * credentials. Both need an unbound `agents:admin` key and belong to the
+ * people who run Channlize: the dashboard, or `@channlize/core`
+ * (`agents.exports`, `agents.telemetry`). An agent reads its own history
+ * with `search_agent_messages` and its numbers with the insights tools,
+ * which only see what its key may read.
+ */
+
+type Json = Record<string, unknown>;
+type Query = Record<string, string | number | boolean | undefined>;
+/** What a handler needs: `ChannlizeApi` from this package, or your own. */
+interface AgentsRequester {
+    request<T>(method: HttpMethod, path: string, 
+    /** `timeout` (ms) overrides the default, for the `get_answer` long-poll. */
+    options?: {
+        query?: Query;
+        body?: unknown;
+        timeout?: number;
+    }): Promise<T>;
+    /** The agent to act as when a call doesn't pass `agentId`. */
+    readonly agentId?: string;
+}
+/** The API key scope a tool needs. */
+type AgentScope = 'agents:send' | 'agents:read' | 'agents:ask_human' | 'agents:admin';
+interface AgentTool<I extends z.ZodObject = z.ZodObject, O extends z.ZodObject = z.ZodObject> {
+    name: string;
+    title: string;
+    description: string;
+    scope: AgentScope;
+    /** The HTTP endpoint it calls, for docs and logs. */
+    endpoint: string;
+    inputSchema: I;
+    outputSchema: O;
+    annotations: ToolAnnotations;
+    handler: (api: AgentsRequester, args: z.output<I>) => Promise<z.output<O>>;
+}
+/** Task lifecycle (same values as the API). */
+declare const AGENT_TASK_STATUSES: readonly ["open", "working", "input_required", "completed", "failed", "canceled", "rejected"];
+/** The longest single long-poll the API holds (`/questions/:id/wait`). */
+declare const QUESTION_WAIT_MAX_SECONDS = 25;
+declare const AGENT_TOOLS: readonly AgentTool[];
+declare const AGENT_TOOL_NAMES: string[];
+declare function getAgentTool(name: string): AgentTool | undefined;
+/**
+ * Validate `args` against the tool's input schema and run it. Throws
+ * `ToolError` for an unknown tool or invalid arguments, and for API
+ * failures (`toToolError` in `api.ts` words them for the model).
+ */
+declare function runAgentTool(api: AgentsRequester, name: string, args: unknown): Promise<Json>;
+/**
+ * The tools as JSON Schema function definitions, for LLM APIs that take
+ * `{ name, description, parameters }` (OpenAI / OpenRouter style).
+ */
+declare function agentToolsAsJsonSchema(filter?: (tool: AgentTool) => boolean): Array<{
+    name: string;
+    description: string;
+    parameters: Json;
+}>;
+
+export { AGENT_TASK_STATUSES, AGENT_TOOLS, AGENT_TOOL_NAMES, QUESTION_WAIT_MAX_SECONDS, agentToolsAsJsonSchema, getAgentTool, runAgentTool };
+export type { AgentScope, AgentTool, AgentsRequester };

package/dist/agents.d.ts

@@ -0,0 +1,94 @@
+import * as z from 'zod/v4';
+import { ToolAnnotations, HttpMethod } from './inbox.js';
+import '@channlize/core';
+
+/**
+ * The Channlize for Agents toolset: names, zod input/output schemas and
+ * handlers for talking to other agents and to people in agent channels,
+ * through `/v1/agents`.
+ *
+ * Like `inbox.ts`, it has no dependency on the MCP server or its
+ * transports, so any agent can import it (`@channlize/mcp/agents`): the
+ * stdio/HTTP server registers these tools (`registerAgentTools` in
+ * `tools.ts`), and an LLM loop can run the same handlers with its own client
+ * (anything with a `request(method, path, { query, body })`).
+ *
+ * Identity: the key decides who the tools act as. An agent key acts as its
+ * agent; a multi-agent key acts as one of its agents, picked by `agentId`
+ * on the call or the requester's default `agentId` (`CHANNLIZE_AGENT_ID` /
+ * `--agent-id` on the server).
+ *
+ * Scopes: `agents:send` (post messages, create, update and hand off
+ * tasks, answer escalated questions), `agents:read` (directory, channels,
+ * inbox and ack, tasks, the org chart, search, and the graph, cost and
+ * metrics insights), `agents:ask_human` (ask people and read the answer)
+ * and `agents:admin` (`get_effective_policy` only).
+ *
+ * No admin-write tools: changing policies, teams, the org chart or an
+ * agent's status stays in the dashboard or `@channlize/core` with an
+ * `agents:admin` key. Policies are the guardrails on what an agent may do,
+ * so the agent that runs these tools shouldn't be able to rewrite them.
+ *
+ * No export or telemetry tools either (Phase 4): exports dump the org's
+ * whole history (messages, tasks, questions, the audit log), and the
+ * telemetry settings choose where every agent's traces go, with
+ * credentials. Both need an unbound `agents:admin` key and belong to the
+ * people who run Channlize: the dashboard, or `@channlize/core`
+ * (`agents.exports`, `agents.telemetry`). An agent reads its own history
+ * with `search_agent_messages` and its numbers with the insights tools,
+ * which only see what its key may read.
+ */
+
+type Json = Record<string, unknown>;
+type Query = Record<string, string | number | boolean | undefined>;
+/** What a handler needs: `ChannlizeApi` from this package, or your own. */
+interface AgentsRequester {
+    request<T>(method: HttpMethod, path: string, 
+    /** `timeout` (ms) overrides the default, for the `get_answer` long-poll. */
+    options?: {
+        query?: Query;
+        body?: unknown;
+        timeout?: number;
+    }): Promise<T>;
+    /** The agent to act as when a call doesn't pass `agentId`. */
+    readonly agentId?: string;
+}
+/** The API key scope a tool needs. */
+type AgentScope = 'agents:send' | 'agents:read' | 'agents:ask_human' | 'agents:admin';
+interface AgentTool<I extends z.ZodObject = z.ZodObject, O extends z.ZodObject = z.ZodObject> {
+    name: string;
+    title: string;
+    description: string;
+    scope: AgentScope;
+    /** The HTTP endpoint it calls, for docs and logs. */
+    endpoint: string;
+    inputSchema: I;
+    outputSchema: O;
+    annotations: ToolAnnotations;
+    handler: (api: AgentsRequester, args: z.output<I>) => Promise<z.output<O>>;
+}
+/** Task lifecycle (same values as the API). */
+declare const AGENT_TASK_STATUSES: readonly ["open", "working", "input_required", "completed", "failed", "canceled", "rejected"];
+/** The longest single long-poll the API holds (`/questions/:id/wait`). */
+declare const QUESTION_WAIT_MAX_SECONDS = 25;
+declare const AGENT_TOOLS: readonly AgentTool[];
+declare const AGENT_TOOL_NAMES: string[];
+declare function getAgentTool(name: string): AgentTool | undefined;
+/**
+ * Validate `args` against the tool's input schema and run it. Throws
+ * `ToolError` for an unknown tool or invalid arguments, and for API
+ * failures (`toToolError` in `api.ts` words them for the model).
+ */
+declare function runAgentTool(api: AgentsRequester, name: string, args: unknown): Promise<Json>;
+/**
+ * The tools as JSON Schema function definitions, for LLM APIs that take
+ * `{ name, description, parameters }` (OpenAI / OpenRouter style).
+ */
+declare function agentToolsAsJsonSchema(filter?: (tool: AgentTool) => boolean): Array<{
+    name: string;
+    description: string;
+    parameters: Json;
+}>;
+
+export { AGENT_TASK_STATUSES, AGENT_TOOLS, AGENT_TOOL_NAMES, QUESTION_WAIT_MAX_SECONDS, agentToolsAsJsonSchema, getAgentTool, runAgentTool };
+export type { AgentScope, AgentTool, AgentsRequester };