The claude-intercom-mcp server enables Claude Code sessions to communicate and coordinate with other coding agents (Claude, Pi, Codex, OpenCode) on the same machine through a shared local messaging system.
Identity (intercom_whoami): Retrieve this session's intercom ID, name, cwd, and model so other sessions can reliably target it.
Status (intercom_status): View broker connection status, active sessions, unread message counts, and pending asks.
Discovery (intercom_list): List all intercom-connected sessions on the machine, optionally filtered by machine, directory, or repo scope.
Publish a summary (intercom_set_summary): Broadcast a short description of what this session is doing so peers can discover your activity.
Send non-blocking messages (intercom_send): Fire-and-forget a direct message (with optional file/snippet/context attachments) to another session by name, full ID, or ID prefix.
Ask and wait for a reply (intercom_ask): Send a question and block until it replies (configurable timeout up to 120 seconds), with optional attachments — useful for synchronous inter-agent coordination.
Read incoming messages (intercom_pending): Retrieve queued inbound messages and unresolved asks directed at this session.
Reply to an inbound ask (intercom_reply): Respond to a pending ask from another session; if only one ask is pending, the target can be omitted for convenience.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@claude-intercom-mcp ask worker-a to inspect the failing test"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Agent Intercom is a cross-harness, same-machine messaging system for coding agents. Its Pi, Codex, Claude Code, and OpenCode adapters share one local broker and protocol, so sessions can discover and message each other regardless of which harness they run in.
Harness | Repository |
Pi | |
Codex | |
Claude Code | |
OpenCode | |
Fleet lifecycle |
Agent Intercom grew from Nico Bailon's original pi-intercom. A sincere thank you to Nico and the original contributors for creating the Pi extension and the foundation this cross-harness family builds on.
This repository contains the Claude Code adapter. It uses the shared strict pi-intercom protocol v3. Any adapter may start the broker first; incompatible legacy brokers are detected and replaced. Sends are retained in a durable per-session outbox and replayed after reconnect, while receiver acknowledgement distinguishes broker acceptance from durable receipt.
Attached Claude sessions support two local delivery transports. native bridges the broker to Claude Code's cross-session Unix socket protocol; mcp preserves the plugin/inbox/Monitor path. The default auto mode attempts native for Claude Code 2.1.220 and newer, then falls back to MCP if native attachment fails. Older or unreadable versions use MCP, while explicit native selection fails closed when the minimum version is not met or attachment fails.
When running cci or ccim in an attached terminal, press Alt+M to choose a connected session and send it a message, or Alt+I to copy that worker's intercom contact target. The MCP plugin cannot register native Claude Code keyboard shortcuts because Claude Code does not expose plugin keybinding registration; the plugin instead provides /claude-intercom:intercom and /claude-intercom:intercom-id. Detached worker-daemon mode has no terminal shortcuts.
Claude Intercom adds local messaging between Claude Code, Codex, Pi, OpenCode,
and other coding-agent sessions on the same machine. It speaks the same local broker
protocol as pi-intercom and
codex-intercom, so sessions
can discover each other, send updates, ask blocking questions, read pending
messages, and reply to asks across all four supported harnesses.
The project has two related pieces:
claude-intercom-mcp: an MCP server that exposes intercom tools inside a
normal Claude Code session.
cci / claude-intercom-worker: a wakeable Claude worker. It registers
an intercom identity, and when another session sends it work, it starts a
fresh headless claude -p turn that resumes the worker's own conversation —
so the worker can read files, run commands, edit code, and reply on its own.
Use plain MCP when you only need tools inside an already-active Claude turn. Use a wakeable worker when you want another session to wake Claude automatically and have it act with real system access.
Related MCP server: Codex Peers MCP
Preview. This is the Claude-side adapter, built alongside pi-intercom and
codex-intercom.
A plain Claude Code MCP session does not receive unsolicited visible turns.
Incoming messages are queued while the MCP server is running; call
intercom_pending to read them. Wake-on-message workflows use cci /
claude-intercom-worker.
Claude Code has no long-lived programmatic "app-server" the way Codex does, so the worker uses the most robust primitive available: the headless CLI.
The worker registers an intercom identity on the local broker and idles.
When a message arrives, the worker runs
claude -p --output-format json --resume <session-id> ..., feeding the
message text on stdin. Normal cci workers automatically receive the
packaged Intercom MCP server, even under an isolated CLAUDE_CONFIG_DIR or
custom ANTHROPIC_BASE_URL.
Claude runs a full turn — it can use Bash, Read, Edit, and every other
Claude Code tool, subject to the worker's permission mode — and prints a
final result plus a stable session_id.
The worker persists that session_id so the next message resumes the same
conversation, and (for blocking asks) sends the final assistant message back
to the asker as the reply.
This gives a woken worker genuine access to the system while keeping each worker
a continuous, resumable conversation. You can attach to a worker's conversation
at any time with claude --resume <session-id>.
Alternative for live sessions: community tools such as
claude-code-inter-sessiondeliver messages into an already-running session using Claude Code'sMonitortool, and Claude Code's experimental Channels feature can push notifications over MCP stdio. Those wake a session you are actively watching; the headless worker here wakes an autonomous background worker with full tool access and needs no experimental features. See docs/wake-mechanisms.md.
Install the package so the command-line entry points are on PATH:
npm install -g @dataforxyz/agent-intercom-claudeThis provides:
claude-intercom-mcp
claude-intercom-worker
cci — start a normal wakeable worker
ccim — start a minimal wakeable worker (cci --minimal)
To let a Pi manager create Claude workers with owned systemd cgroups, leases, model/effort selection, logs, and verified cleanup, install the companion Pi packages:
pi install npm:@dataforxyz/agent-intercom-pi
pi install npm:@dataforxyz/agent-intercom-orchestratorRestart Pi or run /reload, then call agent_fleet({ action: "doctor" }). The orchestrator invokes the installed cci/ccim commands; it does not replace this Claude adapter.
cci and ccim are the recommended entry points when you want an attached,
wakeable Claude session. Unlike a plain MCP session or a detached headless
worker, the attached wrappers provide the Alt+M session picker/message
composer and the Alt+I contact-copy shortcut; they also keep an intercom
identity online so another agent can wake the worker.
If you use the same worker profiles repeatedly, add memorable shell aliases
with your own portable project paths and stable IDs:
alias claude-reviewer='cci --cwd "$HOME/src/my-project" --name reviewer --id reviewer'
alias claude-reviewer-min='ccim --cwd "$HOME/src/my-project" --name reviewer-min --id reviewer-min'Put aliases in your shell startup file (for example ~/.bashrc or ~/.zshrc).
They are optional convenience shortcuts: the installed cci and ccim
commands work directly, but aliases make stable identities and project-specific
defaults easier to reuse without copying a long command.
For a plain, already-active Claude Code session, add the MCP server explicitly:
claude mcp add claude-intercom -- claude-intercom-mcpWith --transport mcp, cci does this automatically for each normal headless worker. Native headless workers are still woken and replied through the worker daemon's broker connection, but omit the packaged MCP server from the Claude turn. ccim intentionally uses Claude's --safe-mode, which disables MCP servers along with plugins, hooks, and skills.
Optional identity variables can be attached at registration time:
claude mcp add claude-planner \
--env CLAUDE_INTERCOM_NAME=planner \
--env CLAUDE_INTERCOM_SESSION_ID=claude-planner \
--env CLAUDE_INTERCOM_MODEL=opus \
-- claude-intercom-mcpThe repo also ships Claude Code plugin metadata:
.claude-plugin/plugin.json
.mcp.json
skills/claude-intercom/SKILL.md
commands/intercom.md and commands/intercom-id.md
The plugin packages the MCP server and the bundled claude-intercom skill (which
gives Claude copy-paste coordination patterns). It also installs these Claude
Code slash commands:
/claude-intercom:intercom [target and message] — list sessions and send a
message. Without arguments, Claude asks which peer to contact and what to send.
/claude-intercom:intercom-id — print this session's stable, copyable
intercom target.
Claude custom commands are model-driven prompt commands, not native modal UI.
Claude namespaces plugin commands by plugin name, so an installed plugin cannot
claim the unqualified /intercom command globally.
They call the same MCP tools and work in a normal Claude Code session, but only
the attached cci/ccim wrappers can own the terminal and provide an immediate
Alt+M picker. Load the plugin for a single session with --plugin-dir:
claude --plugin-dir /path/to/agent-intercom-claude # this session onlyFor the minimal tool surface, prefer plain MCP registration
(claude mcp add claude-intercom -- claude-intercom-mcp) so you get the intercom
tools without the skill.
intercom_whoami: show this session's intercom ID, name, cwd, and model.
intercom_team: show the current manager and live coworkers owned by that manager.
intercom_status: show connection status and pending message counts.
intercom_list: list local Pi, Codex, and Claude sessions globally.
intercom_set_summary: publish a short discoverable status.
intercom_send: send a non-blocking message.
intercom_ask: send a question and wait for the target's reply.
intercom_pending: read queued inbound messages and unresolved asks.
intercom_reply: reply to a pending inbound ask; use to plus which: "oldest" | "latest" if one sender has multiple unresolved asks.
Pending output never exposes protocol message IDs. Keep at most one unresolved intercom_ask to the same recipient; the broker rejects a second ask and recommends intercom_send for a non-blocking follow-up. Use intercom_send—not intercom_ask—for assignments and progress/status checkpoints.
Persistent Claude workers and plain MCP runtimes automatically reconnect their stable Intercom identity after a broker restart, so a live worker does not need to be respawned merely to become reachable again.
Example:
intercom_team({})
// Manager: manager-id [connected]
// You: worker-a
// Coworkers: reviewer target=reviewer (codex, reviewer, running) [connected]
intercom_ask({
to: "worker-a",
message: "Please inspect the failing test and reply with the likely cause.",
timeout_ms: 45000
})Blocking asks default to a short bounded wait and reject waits over 120 seconds.
For longer work, use intercom_send and check later with intercom_pending.
ccicci (Claude Code Intercom) starts a single wakeable worker in the foreground.
It registers the worker on the broker. For every inbound message, the attached
terminal visibly prints the sender and message, a working indicator, and the
final Claude result or error. Blocking asks still receive that final result as
their automatic intercom reply. Press Alt+M for a numbered list of connected
peers, then choose one and enter a message. Press Alt+I to copy the worker's
contact target.
This is an attached worker console, not Claude Code's interactive TUI: woken
turns run through claude -p, and their final output is mirrored into the
console. To continue or inspect the full Claude conversation, run claude --resume <session-id> using the session ID printed with the completed turn.
ccim has the same visible wake behavior and shortcuts.
Start a named worker:
cci --name worker-a --id worker-aFlags (all optional; ccim accepts the same set):
Flag | Meaning |
| Discoverable session name other sessions target |
| Stable intercom session id (defaults to a git-derived id) |
| Working directory for the worker's turns (default: cwd) |
| Model for woken turns ( |
| Claude effort for every woken turn ( |
| System-prompt guidance appended to every woken turn |
| Run as a LIVE interactive Claude session woken in place (see below) instead of a headless |
| Run woken turns with |
| Compatibility alias for the safe |
| Explicitly bypass permission checks (never the default) |
| Validated against Claude Code 2.1.220 ( |
| Extra directory the worker may access (repeatable) |
| Extra MCP servers for woken turns (e.g. to give the worker intercom tools) |
| Where to persist the worker's session id (default under |
| Claude Code executable to invoke (default |
| Delivery transport; |
cci --cwd /path/to/project --instructions "Reply tersely. Ask before destructive changes."
cci --model opus --effort max --name reviewer --id reviewer
cci --yolo --name trusted-worker --id trusted-worker # explicit opt-in only
cci --add-dir ../shared-lib --name worker-a --id worker-aBy default cci passes the standard --permission-mode manual; it never adds
--dangerously-skip-permissions on the user's behalf. Headless turns cannot
answer an interactive permission prompt, so choose a validated explicit mode
when a different non-interactive posture is required. --yolo remains an
explicit trusted-user opt-in outside hardened roles.
cci --tui)Default cci is a headless worker: each message spawns a claude -p turn. With
--tui, cci instead opens a live interactive Claude session that you sit in
and that is woken in place — the Codex coi experience. Inbound intercom
messages are injected into the running session and it replies over the broker;
you see everything and can type alongside it.
cci --tui --name worker-a --id worker-aClaude Code has no Codex-style app-server. cci --tui therefore resolves one of two local transports before launch:
Native bridges the Intercom broker to Claude Code's local cross-session Unix socket. Inbound messages appear as attributed peer messages in the live session; Claude must answer them with its built-in SendMessage tool so the bridge can preserve blocking ask/reply correlation. Native launches enable Claude's cross-session feature flag automatically. auto attempts native on Claude Code 2.1.220 and newer. If native attachment fails under auto, cci restarts once with MCP; explicit --transport native fails closed instead.
MCP is the preserved compatibility path. It launches Claude with the packaged plugin, whose MCP server registers the identity, appends inbound messages to a durable inbox, and auto-arms monitors/monitors.json to inject them with Claude Code's local Monitor mechanism. Blocking asks are answered with intercom_reply.
Choose explicitly with --transport native or --transport mcp, or set CLAUDE_INTERCOM_TRANSPORT. Worker JSON entries also accept "transport": "auto" | "native" | "mcp". The Claude executable is probed with claude --version; unreadable or out-of-window versions never silently enable native mode.
--minimal is ignored in live TUI mode. The native path requires an interactive Claude process that publishes its local messaging socket. The MCP path additionally needs a built checkout (npm run build) and an available Monitor feature; Monitor is unavailable when DISABLE_TELEMETRY or CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC is set, or on Bedrock/Vertex/Foundry. Both paths remain local and work behind a custom ANTHROPIC_BASE_URL/proxy. See docs/wake-mechanisms.md.
Like Codex's coi (normal) and coim (minimal), cci has a minimal mode. Codex
needs a dedicated CODEX_HOME and a hand-written config.toml to strip
memories, plugins, skills, and browser surfaces (while keeping multi_agent).
Claude Code has this built in: cci --minimal runs every woken turn with Claude
Code's --safe-mode, which disables CLAUDE.md, skills, plugins, hooks, and MCP
servers while keeping auth, built-in tools (Bash/Read/Edit/…), and permissions
working normally. It is the focused-worker profile: less prompt and tool surface,
same coding ability.
Subagents are retained in minimal mode. --safe-mode only disables custom
agent-type definitions (.claude/agents/), not the built-in Task tool — so a
minimal worker can still delegate to general-purpose subagents, matching Codex
minimal's multi_agent = true. This is verified end-to-end
(test/e2e/minimal-subagent.sh): a minimal worker spawns a subagent that runs a
shell command and reports back.
cci and ccim are installed as a matched pair (like Codex's coi and coim):
ccim is exactly cci --minimal — same flags, same identity handling, minimal
by default. You do not need an alias to enable minimal mode; aliases are useful
only for reusable names, IDs, paths, or permission settings.
cci --name reviewer --id reviewer # normal: full config, CLAUDE.md, skills, MCP
ccim --name lean-worker --id lean-worker # minimal: --safe-mode woken turns
ccim --safe --name lean-safe --id lean-safe # minimal + standard permission prompts
cci --minimal --name worker-a --id worker-a # equivalent to `ccim ...`Because minimal mode disables MCP in the woken turn, a minimal worker cannot use the intercom tools to message other sessions itself — it still receives work and replies normally (the worker daemon captures its final message and sends the reply). Use a normal worker when you want the woken turn to reach out to peers on its own.
Use one Claude Code session as the manager and one or more cci workers.
Launch a worker in tmux:
tmux new-session -d -s worker-a 'cd /path/to/project && cci --name worker-a --id worker-a'Then, from the manager session, delegate through the intercom tools:
intercom_ask({
to: "worker-a",
message: "Create a plan for adding retries to src/api/client.ts, then report your first step.",
timeout_ms: 60000
})For non-blocking delegation, use intercom_send and check back with
intercom_pending. For a decision you need before continuing, use
intercom_ask.
Use claude-intercom-worker when you want one process to publish several
configured workers without a launcher per worker.
Create a config:
{
"statePath": "/path/to/intercom/claude-worker-state.json",
"claudeCommand": "claude",
"agents": [
{
"id": "claude-worker",
"name": "claude-worker",
"cwd": "/path/to/project",
"model": "sonnet",
"instructions": "Reply concisely. Ask before making destructive changes.",
"permissionMode": "manual"
}
]
}Worker configuration validates permission modes and rejects permission flags
hidden in claudeArgs. A tightening-only bossRole hint of adversary or
council forces --bare, permissionMode: "plan", and a read-only ceiling;
permission-granting settings, agents, plugins, and appended argv cannot widen
it. This local hint does not enroll a Boss participant or expose a reviewer
tool; those surfaces stay unavailable until a protected Controller supplies the
binding, transport, and durable dispatch path.
Start it:
claude-intercom-worker --config "$HOME/.pi/agent/intercom/claude-worker.json"Each worker's session_id is persisted in statePath, so later messages resume
the same Claude conversation. The daemon reads a single worker's config from the
environment when no config file is given (CLAUDE_INTERCOM_WORKER_ID, …_NAME,
…_CWD, …_MODEL, …_INSTRUCTIONS, …_STATE).
Variable | Used by | Purpose |
| MCP server | Discoverable session name |
| MCP server | Stable intercom id |
| MCP server | Model label shown to peers |
|
| Effort level forwarded to every Claude turn |
|
| Defaults for |
| workers | Claude Code executable (default |
|
| Single-worker config when no |
|
| Path to the worker config JSON |
| all | Default blocking-ask timeout (≤ 120000) |
| all | Overrides the |
The PI_* names are shared with the Pi, Codex, and OpenCode adapters on purpose —
all four read the same broker location and ask-timeout so they interoperate.
git clone https://github.com/dataforxyz/agent-intercom-claude.git
cd agent-intercom-claude
npm install
npm run build
npm testFor MCP development, register the TypeScript source directly:
claude mcp add claude-intercom-dev -- npx --no-install tsx ./claude/server.tsagent-intercom-pi is the Pi-native adapter with overlays and inline rendering.
agent-intercom-codex is the Codex MCP/plugin adapter plus wake-on-message Codex
app-server sidecars. This repository, agent-intercom-claude, is the Claude Code
MCP/plugin adapter plus wake-on-message headless claude -p workers.
agent-intercom-opencode provides the native OpenCode plugin.
All four vendor the compatible local broker/client protocol and share one broker socket, so a single session list spans Pi, Codex, Claude Code, and OpenCode.
Releases are automated from version tags. Update package.json, the lockfile when
present, and CHANGELOG.md on main, then push an annotated tag that exactly
matches the package version:
git tag -a vX.Y.Z -m "vX.Y.Z"
git push origin vX.Y.ZThe release workflow verifies that the tag points into main, runs typecheck,
tests, and the build, publishes the public npm package with trusted OIDC
provenance, and creates the GitHub Release. Existing npm versions and GitHub
Releases are skipped safely when a workflow is rerun.
The current project is licensed under the GNU Affero General Public License
v3.0 or later (AGPL-3.0-or-later). If you modify this software and
make the modified version available to users over a network, the AGPL requires
you to offer those users the corresponding source code.
Portions derived from the original MIT-licensed pi-intercom project retain
their original notices. See THIRD_PARTY_NOTICES.md and
licenses/MIT-pi-intercom.txt. Versions already
published under MIT remain available under their original terms. See
LICENSE_TRANSITION.md for the exact commit and tag boundary.
Ask another intercom session a question and wait for its reply.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | ||
| message | Yes | ||
| timeout_ms | No | Maximum time to wait for a reply before returning an error. Use intercom_send plus intercom_pending for longer work. | |
| attachments | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavioral traits. It mentions waiting for a reply but does not explain potential outcomes like timeout errors, blocking behavior, or the format of replies. The timeout_ms parameter hints at timeouts, but this is not in the description itself.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that directly states the tool's function without extraneous words. It is efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters, no output schema, and no annotations, the description is too sparse. It does not explain return values, input requirements, or error behaviors, leaving significant gaps for an AI agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25% (only timeout_ms has a description). The tool description adds no meaning to parameters: 'to' and 'message' are unexplained, and attachments structure is not clarified. The description fails to compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: asking another intercom session a question and waiting for a reply. It effectively distinguishes itself from siblings like intercom_send (send without waiting) and intercom_reply (reply to a question).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies synchronous use by mentioning 'wait for its reply'. The timeout_ms parameter description provides guidance to use intercom_send plus intercom_pending for longer work, offering limited usage guidance. However, the main description lacks explicit when-to-use or when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List intercom-connected Pi or Claude sessions on this machine.
| Name | Required | Description | Default |
|---|---|---|---|
| scope | No | machine | |
| include_self | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry behavioral disclosure. It only states 'list', suggesting read-only, but fails to disclose other traits like whether there are side effects, the meaning of 'intercom-connected', or what happens on no results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that gets straight to the point. However, it omits parameter information, which would improve completeness without sacrificing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (2 params, no output schema), the description is too minimal. It fails to explain what Intercom is, what a 'session' entails, the effect of parameters, or the return format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has two parameters (scope, include_self) with 0% description coverage, but the tool description does not mention any parameter details, leaving the agent uninformed about how to use them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and the resource ('intercom-connected Pi or Claude sessions') with a scope ('on this machine'). It distinguishes from sibling tools that perform actions like ask, send, reply, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (listing sessions on this machine) but provides no explicit guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read unread inbound messages and unresolved asks for this Claude session.
| Name | Required | Description | Default |
|---|---|---|---|
| mark_read | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It fails to mention that the 'mark_read' parameter can change state (mark messages as read), nor does it explain the scope ('for this Claude session' is mentioned but without details on session boundaries or side effects).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no redundant words. Every part adds value, achieving maximum conciseness for the intended purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (1 optional parameter, no output schema), the description covers the core purpose but lacks detail on the parameter's behavior and any side effects. It is minimally viable but could be more helpful with additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the parameter 'mark_read' has no description in the schema. The tool description also omits any explanation of this parameter, leaving the agent to infer meaning from the name alone. This is inadequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Read' and specifies the resources: 'unread inbound messages and unresolved asks'. It distinguishes itself from sibling tools like intercom_ask (send an ask), intercom_reply (reply), intercom_send (send), etc., by focusing on reading pending items.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when needing to retrieve unread messages and unresolved asks, but it does not explicitly state when to avoid using it (e.g., for listing all messages) or compare with alternatives like intercom_list or intercom_status. Guidance is minimal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reply to a pending inbound ask. If exactly one ask is pending, to/reply_to can be omitted.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | ||
| message | Yes | ||
| reply_to | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only says 'reply to a pending inbound ask' without detailing behavior like whether it creates a new message, modifies the ask, or requires specific permissions. This is insufficient for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short with two sentences, front-loading the purpose. It is concise, but could benefit from slightly more detail without excessive length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and a simple action, the description is somewhat complete for the core purpose but lacks context on the outcome of replying (e.g., whether it sends immediately, thread behavior). It does not address error cases or prerequisites.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no descriptions (0% coverage). The description only hints that 'to' and 'reply_to' can be omitted under a condition, but does not explain their meaning or format. For a tool with three parameters, this is inadequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it replies to a pending inbound ask, which conveys the action. It distinguishes from sibling tools like intercom_ask (asking) and intercom_send (sending messages) by specifying 'reply' to a pending ask, but could further clarify what constitutes an 'ask'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a useful guideline: when exactly one ask is pending, 'to' and 'reply_to' can be omitted. This helps the agent decide how to use the tool efficiently. However, it does not mention when not to use it or provide alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a non-blocking direct message to another intercom session by name, full ID, or unique ID prefix.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | ||
| message | Yes | ||
| attachments | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. Mentions 'non-blocking' which hints at asynchronous behavior, but no details on side effects, permissions, rate limits, or success/failure signaling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence of 15 words, efficient and front-loaded with verb and resource. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 3 parameters, no output schema, and no annotations, the description is too sparse. Missing return value, error conditions, authentication requirements, and details on attachments subtype specifications.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions are missing (coverage 0%). The tool description adds context for 'to' parameter (by name, full ID, or prefix) but no elaboration on 'message' or 'attachments' structure, required fields, or allowed values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'Send' and resource 'direct message to another intercom session' with methods to identify recipient. However, it doesn't explicitly distinguish from sibling tools like intercom_reply, which could be for replying. The 'non-blocking' qualifier adds clarity but is not explained further.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Only implies when to use (sending a direct message). No guidance on when not to use, prerequisites, or alternatives among siblings (e.g., intercom_reply for replies).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Publish a short status summary so other sessions can discover what this Claude session is doing.
| Name | Required | Description | Default |
|---|---|---|---|
| summary | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully convey behavioral traits. It indicates a write operation ('publish') and the purpose, but does not mention whether it overwrites previous summaries or any authentication needs. The transparency is adequate for a simple set action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, well-structured sentence with no unnecessary words. The action and purpose are front-loaded, making it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one parameter and no output schema, the description is fairly complete. It explains the tool's function and rationale. However, it could mention that the summary overwrites any previous summary for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must elaborate on the 'summary' parameter. However, it only refers to 'short status summary' without adding constraints (e.g., maxLength 400 is in schema but not described), conventions, or examples. This provides minimal added value beyond the parameter name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'publish' and the resource 'status summary', and explains the purpose: enabling other sessions to discover what this session is doing. This distinguishes it effectively from siblings like intercom_status (read status) or intercom_list (list items).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (to share current activity with other sessions) but does not explicitly state when not to use or mention alternatives. The context from sibling tools helps, but direct exclusion criteria are missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show intercom connection status, active sessions, unread messages, and pending asks.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. The verb 'Show' implies a read-only operation, but the description does not explicitly state that it does not modify state. The absence of any mention of side effects or permissions leaves room for ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the action and lists the outputs. Every word adds value, no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool without output schema, the description covers the main information: what the tool returns. It lacks details like whether the status is real-time or requires a connection, but for a simple status check, it is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, and the schema coverage is 100% (empty). The description adds meaning by stating what data is shown, which is helpful but not essential since there are no parameters to clarify.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Show' and lists the exact resources: connection status, active sessions, unread messages, and pending asks. This clearly distinguishes it from siblings like 'intercom_ask' or 'intercom_send'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or context for preferring it over other intercom tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return this Claude session's intercom identity for reliable targeting.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description does not disclose any behavioral traits such as read-only nature, auth needs, or side effects. For a whoami tool, it is likely safe, but this is not stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words. Front-loaded with action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low complexity (no parameters, no output schema), the description is sufficient. It states what it returns and hints at its purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is 100%. Description does not need to add parameter details; baseline is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Verb 'Return' and resource 'intercom identity' are specific. Context 'this Claude session' clarifies scope. Clearly distinguishes from sibling tools that involve asking, listing, replying, sending, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'for reliable targeting' indicates when to use it (to obtain identity for targeting). While it does not explicitly state when not to use it, the purpose is self-evident given sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.2.0intercom_askintercom_listintercom_pendingintercom_replyintercom_sendintercom_set_summaryintercom_statusintercom_whoamiEach tool has a clearly distinct purpose: asking questions, listing sessions, checking pending messages, replying, sending DMs, setting summaries, checking status, and identifying oneself. No overlap or ambiguity.
All tools share the 'intercom_' prefix with descriptive verbs or nouns. While some use plain verbs (ask, list, reply, send) and others use state nouns (pending, status, whoami) or verb_noun (set_summary), the pattern is predictable and clear.
8 tools is ideal for the domain of inter-session communication. Each tool serves a necessary function without redundancy, covering sending, receiving, discovery, and status.
The tool set covers all essential operations for inter-session messaging: sending (both blocking and non-blocking), reading, replying, discovering sessions, displaying status, and self-identification. No obvious gaps like broadcast or notification are needed for basic communication.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
End-to-end encrypted messaging and work coordination for autonomous AI agents.
Real-time chat for AI agents. Claude Code, Cursor, Cline and Codex join channels over MCP.
The team layer for AI coding agents: shared contracts, collision alerts, E2EE sessions.
Real-time chat hub for AI agents — Claude Code, Cursor, Cline, Codex over MCP or REST.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/dataforxyz/agent-intercom-claude'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
