mcp-await
Provides a tool to monitor Docker containers and block until a container exits, facilitating orchestration within AI workflows.
Enables the ability to watch and wait for specific GitHub Actions workflow runs to complete using the GitHub CLI.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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 --releaseRelated MCP server: Run Command MCP Server
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 30Tools
Tool | Key Params | How it watches |
|
| TCP dial loop, 500ms interval |
|
| inotify via |
|
|
|
|
|
|
|
|
|
|
|
|
|
| Re-run via |
|
| 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 30Exit 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-awaitBlocking 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: falseGet back immediately:
{"watch_id": "port-1", "resource": "watch://port-1", "status": "watching"}Do other work while waiting
Receive
notifications/resources/updatedwhen the condition is metRead
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 |
|
Codex |
|
Gemini CLI |
|
Cursor |
|
Windsurf |
|
## 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 # formatLicense
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Dead-man switch monitors for cron & AI agents with dependency-cascade alerts. No account needed.
Let agents make HTTP requests later: schedule, retry, cron, watch jobs, receive webhooks.
Dead-man's-switch for cron jobs & AI agents. Import a crontab to arm one silent-miss alert per job.
Outcome-verified watchdog for scheduled agents. $0.002/check.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables execution of bash commands with support for timeouts and background jobs, allowing file operations, build commands, system inspection, and long-running tasks.362368 npm9MIT
- FlicenseAqualityCmaintenanceProvides tools for executing shell commands both synchronously and asynchronously with real-time output streaming and process management capabilities. It enables users to start background tasks, monitor progress, and manage long-running processes via Stdio or HTTP transports.3-
- AlicenseNot gradedqualityDmaintenanceProvides a wait tool for AI agents to pause execution until a time duration elapses or a process terminates, useful for polling and waiting for builds/deployments.MIT
- AlicenseAqualityDmaintenanceProvides blocking await tools to poll commands, URLs, or files until a condition is met, eliminating the need for sleep loops in agent workflows.3MIT