Mcp Await
@ricardo-hdrn
Condition watcher for AI assistants — wait for ports, files, URLs, processes, and more
Overview
What is Mcp Await?
Mcp Await is a condition-watcher MCP server and CLI for AI CLI assistants (Claude Code, Codex, Cursor, etc.). Instead of polling with loops and retries, it blocks until a condition (e.g., port open, file created, command succeeds) is met and returns the result.
How to use Mcp Await?
Install via cargo install mcp-await or download a prebuilt binary from GitHub Releases. Run as a CLI with subcommands like mcp-await port localhost 8080 --timeout 30 or as a stdio MCP server by invoking the binary without a subcommand (or with mcp-await serve). Configure it in Claude Code by adding the binary path to ~/.claude.json under mcpServers.
Key features of Mcp Await
- Wait for TCP ports to accept connections.
- Watch file events (create, modify, delete) using inotify.
- Wait for HTTP URLs to return an expected status code.
- Wait for processes to exit via PID.
- Wait for Docker containers to exit.
- Supports blocking and non-blocking watch modes.
Use cases of Mcp Await
- Deployments: wait for a service to be ready before proceeding.
- File-based synchronization: wait for a lock file to appear or be modified.
- CI/CD: wait for a Docker container or GitHub Actions run to finish.
- Custom scripts: wait for any shell command to succeed (exit 0).
FAQ from Mcp Await
What is the difference between blocking and non-blocking mode?
In blocking mode (default), the tool call holds until the condition is met or times out. In non-blocking mode, the tool returns immediately with a watch_id, then the server monitors in the background and pushes a notification when done.
How do I cancel a non-blocking watch?
Use the cancel_watch tool with the watch_id returned from the non-blocking call.
What exit codes does the CLI return?
Exit code 0 means the condition was met (success), 1 means timeout, and 2 means an error occurred.
How do I set up Mcp Await with Claude Code?
Add the binary path to ~/.claude.json under mcpServers as shown in the README.
What tools does the MCP server provide?
Tools include wait_for_port, wait_for_file, wait_for_url, wait_for_pid, wait_for_docker, wait_for_gh_run, wait_for_command, and cancel_watch. All accept timeout_seconds and blocking parameters.
