await-mcp
brycehans/await-mcp
Pause agentes Claude até eventos externos chegarem via webhook
Ver no GitHubMCP server que permite a um agente Claude aguardar sinais externos (webhooks, eventos) sem polling. Claude pausa a execução até que um evento nomeado chegue via HTTP, retomando imediatamente quando disparado. Ideal para fluxos que dependem de ações fora do controle do agente.
Instalação
npx convez-ai brycehans/await-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Aguardar conclusão de deploys ou builds
- Parar fluxo até aprovação manual (Slack, email)
- Esperar pagamentos ou transações completarem
- Sincronizar com eventos de sistemas externos
- Orquestração de workflows multi-etapa
Veredito

Solução elegante para padrão comum: agentes que precisam esperar eventos externos sem desperdício de polling. Implementação limpa com interface HTTP simples e suporte a payloads JSON. Excelente para orquestração de workflows com dependências assíncronas.
README
A tradução para o português deste README ainda está na fila.
await-mcp
A Claude Code plugin that blocks a session until a named external event arrives.
Use it when a task depends on something outside Claude's control — a webhook, a Slack reply, a payment, a deploy finishing, a file appearing. Instead of polling, Claude waits and resumes the moment the event arrives.
Usage
/await "payment complete"
/await deploy-finished
/await slack-approval
From any terminal, script, or webhook handler, fire the event:
# URL form (simplest)
xh GET 'http://127.0.0.1:9876/event/payment%20complete' --ignore-stdin
# JSON form (with optional data payload)
xh POST http://127.0.0.1:9876/event name="payment complete" data:='{"amount":99}' --ignore-stdin
The event name must match exactly what was passed to /await.
How it works
The plugin runs a local Node.js process that listens on two interfaces simultaneously:
- MCP (stdio) — exposes
wait_until_event(name)to Claude Code. When called, it registers a pending waiter and blocks indefinitely. - HTTP (localhost:9876) — accepts
POST /event(JSON body) orGET|POST /event/<name>(URL path). When an event arrives, it resolves all matching waiters.
No polling. No timeout. Claude resumes the instant the HTTP endpoint is hit.
Installation
Register this repo as a local marketplace in ~/.claude/settings.json under extraKnownMarketplaces:
"extraKnownMarketplaces": {
"brycehans": {
"source": {
"source": "directory",
"path": "/path/to/await-mcp"
}
}
}
Then install:
claude plugin install await@brycehans
Configuration
| Environment variable | Default | Description |
|---|---|---|
AWAIT_PORT | 9876 | HTTP port to listen on |
HTTP API
| Method | Path | Body | Description |
|---|---|---|---|
POST | /event | {"name":"...","data":{}} | Fire an event with optional data |
GET|POST | /event/<name> | — | Fire an event by URL path |
GET | /health | — | Liveness check |
The response is always {"ok":true,"resolved":<n>,"name":"...","data":{}} where resolved is the number of active waiters that were unblocked. If resolved is 0, the event arrived before anyone was waiting — it is dropped.
Development
Repo layout
await-mcp/
package.json ← marketplace manifest (name + version only)
.claude-plugin/
marketplace.json ← marketplace index (read by Claude Code CLI)
plugin/ ← installable content — copied to cache on install
.claude-plugin/
plugin.json ← plugin metadata
.mcp.json ← MCP server launch config
index.js ← the MCP + HTTP server
package.json ← dependencies + start script
skills/
await/
SKILL.md ← the /await slash command
Everything under plugin/ is what gets installed. Files at the repo root (outside plugin/) are only read by the marketplace machinery — they are not part of the installed plugin.
Edit → reinstall → reload loop
- Edit files under
plugin/ - Reinstall to refresh the cache:
claude plugin install await@brycehans - Start a new Claude Code session (the MCP server process is spawned fresh per session)
The install command copies plugin/ into ~/.claude/plugins/cache/brycehans/await/<version>/. You do not need to restart between edits to SKILL.md — skills are read at session start from the cache, so reinstall + new session is sufficient.
Running the server standalone
You can start the server outside of Claude Code to test the HTTP side:
cd plugin
bun install
node index.js
The MCP side requires a connected client (Claude Code), but the HTTP server starts regardless. Test it:
xh GET http://127.0.0.1:9876/health
# → ok
xh GET 'http://127.0.0.1:9876/event/test' --ignore-stdin
# → {"ok":true,"resolved":0,"name":"test","data":{}}
resolved: 0 is expected when no waiter is registered — the event is dropped.
Checking the server is running during a session
While /await is blocking inside Claude Code, confirm the HTTP endpoint is up:
xh GET http://127.0.0.1:9876/health
If it returns ok, the server is running and ready to receive events. If it fails, the MCP server process didn't start — check that bun is on PATH and plugin/node_modules/ was installed.
Version bumps
Version numbers live in four places — keep them in sync:
| File | Field |
|---|---|
package.json (root) | version |
.claude-plugin/marketplace.json | metadata.version and plugins[0].version |
plugin/package.json | version |
plugin/.claude-plugin/plugin.json | version |
plugin/index.js | version in new Server({name:'await', version:'...'}) |
After bumping, reinstall — the CLI uses the version to name the cache directory, so a version bump gets a fresh cache slot:
claude plugin install await@brycehans
Marketplace mechanics
Claude Code reads .claude-plugin/marketplace.json at the repo root to enumerate available plugins. That file's plugins[0].source ("./plugin") tells the CLI where the installable content lives. On install, the CLI copies that directory into:
~/.claude/plugins/cache/brycehans/await/<version>/
The installed plugin is registered in ~/.claude/settings.json under enabledPlugins as await@brycehans. The known_marketplaces.json file at ~/.claude/plugins/known_marketplaces.json tracks the marketplace registration separately.
To uninstall:
claude plugin uninstall await@brycehans
To list installed plugins:
claude plugin list