Condition watcher for AI assistants — wait for ports, files, URLs, processes, and more
Condition watcher MCP server for AI assistants — wait for ports, files, URLs, processes, and more. This MCP server + CLI optimizes waiting patterns by blocking until a condition is met, instead of polling with sleep loops and repeated API calls. Integrates with AI CLI assistants (Claude Code, Codex, Cursor, etc.) to synchronize readiness.
🛠️ Key Features
MCP server and CLI for condition-based waits
Supports ports, files, URLs, processes, and additional conditions
Reduces API round-trips by blocking until condition is satisfied
Works with AI CLI assistants for streamlined workflows
🚀 Use Cases
Waiting for a service port to become available before proceeding
Ensuring a file or resource exists prior to execution
Synchronizing multi-step AI workflows with readiness checks
⚡ Developer Benefits
Clear MCP server interface for condition watching
Lightweight, purpose-built for AI assistant integrations
Reusable component to replace polling logic in scripts
⚠️ Limitations
Details on supported condition types may evolve; refer to repository for updates
Readme excerpt focuses on general usage; deeper configuration may be required for advanced scenarios
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.
demo
Installation
bash
# 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
bash
# 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).
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.
Receive notifications/resources/updated when the condition is met
Read watch://port-1 for the full result
Cancellation
Cancel any non-blocking watch with cancel_watch:
json
{"watch_id":"port-1"}
Resources
Non-blocking watches are exposed as MCP resources at watch://{watch_id}.
list_resources — returns all active and completed watches
read_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
markdown
## 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)
