mcp-await
Condition watcher MCP server + CLI for AI CLI assistants (Claude Code, Codex, Cursor, etc.).
Instead of polling with sleep loops and curl --retry that waste API round-trips, call a wait tool once — it blocks until the condition is met and returns the result.
Installation
# Prebuilt binary (Linux, macOS, Windows) — download from GitHub Releases
# https://github.com/ricardo-hdrn/mcp-await/releases/latest
# From crates.io
cargo install mcp-await
# From source
git clone https://github.com/ricardo-hdrn/mcp-await.git
cd mcp-await
cargo build --release
Quick Start
# Wait for a service to be ready
mcp-await port localhost 8080 --timeout 30
# Wait for a file to appear
mcp-await file /tmp/deploy.lock --event create --timeout 60
# Wait for a command to succeed
mcp-await cmd "curl -sf http://localhost:8080/health" --interval 2 --timeout 30
Tools
| Tool | Key Params | How it watches |
|---|---|---|
wait_for_port | host, port | TCP dial loop, 500ms interval |
wait_for_file | path, event (create/modify/delete) | inotify via notify crate, no polling |
wait_for_url | url, expected_status (default 200) | curl loop, 2s interval (requires curl) |
wait_for_pid | pid | /proc/{pid} check, 500ms interval |
wait_for_docker | container | docker wait (requires docker) |
wait_for_gh_run | run_id, repo (optional) | gh run watch (requires gh) |
wait_for_command | command, interval_seconds (default 5) | Re-run via sh -c until exit 0 |
cancel_watch | watch_id | Cancels a non-blocking watch |
All tools accept timeout_seconds (default: 300) and blocking (default: true).
CLI Usage
The binary doubles as a standalone CLI tool:
# TCP port
mcp-await port localhost 5432 --timeout 30
# File events
mcp-await file /var/log/app.log --event modify --timeout 120
mcp-await file /tmp/flag --event create --timeout 60
mcp-await file /tmp/old.pid --event delete --timeout 30
# HTTP status
mcp-await url https://api.example.com/health --status 200 --timeout 120
# Process exit
mcp-await pid 12345 --timeout 300
# Docker container exit
mcp-await docker my-container --timeout 600
# GitHub Actions run
mcp-await gh-run 12345678 --repo owner/repo --timeout 1800
# Arbitrary shell command (exit 0 = success)
mcp-await cmd "test -f /tmp/ready" --interval 2 --timeout 30
Exit Codes
| Code | Meaning |
|---|---|
| 0 | Condition met (success) |
| 1 | Timeout |
| 2 | Error |
Output Format
All commands output JSON:
{
"status": "success",
"elapsed_seconds": 1.23,
"detail": "localhost:8080 is accepting connections"
}
MCP Server Setup
Claude Code
Add to ~/.claude.json:
{
"mcpServers": {
"await": {
"command": "/path/to/mcp-await"
}
}
}
The binary runs as a stdio MCP server when invoked without a subcommand (or with mcp-await serve).
MCP Inspector
npx @modelcontextprotocol/inspector ./target/release/mcp-await
Blocking vs Non-Blocking Mode
Blocking (default)
The tool call holds until the condition is met, times out, or is cancelled. This is the simplest mode — the AI assistant waits for the result.
Non-Blocking
Set blocking: false to get an immediate response with a watch_id and resource URI. The server monitors in the background and pushes a notification when done.
Flow:
- Call
wait_for_portwithblocking: false - Get back immediately:
{"watch_id": "port-1", "resource": "watch://port-1", "status": "watching"} - Do other work while waiting
- Receive
notifications/resources/updatedwhen the condition is met - Read
watch://port-1for the full result
Cancellation
Cancel any non-blocking watch with cancel_watch:
{"watch_id": "port-1"}
Resources
Non-blocking watches are exposed as MCP resources at watch://{watch_id}.
list_resources— returns all active and completed watchesread_resource("watch://port-1")— returns JSON with the watch status and result
Reinforcing Agent Usage
Agents sometimes fall back to shell workarounds instead of using mcp-await. Add a snippet to your project's agent instructions file to reinforce the behavior:
| Agent | Instructions file |
|---|---|
| Claude Code | CLAUDE.md |
| Codex | AGENTS.md |
| Gemini CLI | GEMINI.md |
| Cursor | .cursor/rules/ |
| Windsurf | .windsurfrules |
## Waiting for conditions
Use mcp-await tools instead of shell workarounds:
- `wait_for_port` instead of `while ! nc ...; do sleep 1; done`
- `wait_for_url` instead of `curl --retry`
- `wait_for_file` instead of polling loops
- `wait_for_command` instead of `while ! cmd; do sleep N; done`
Prefer `blocking: false` when there is independent work to do in parallel.
Roadmap
- Agent-level instructions to enforce mcp-await usage across all agents (system prompts, tool metadata hints)
- Broader agent compatibility testing (Codex, Gemini CLI, Cursor, Windsurf)
Development
cargo build # debug build
cargo build --release # release build
cargo test # run tests
cargo clippy # lint
cargo fmt # format