Mcp Await

mcp-await

[crates.io] [CI] [license]

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

# Prebuilt binary (Linux, macOS, Windows) — download from GitHub Releases# https://github.com/ricardo-hdrn/mcp-await/releases/latest
# From crates.iocargo install mcp-await
# From sourcegit clone https://github.com/ricardo-hdrn/mcp-await.gitcd mcp-awaitcargo build --release

Quick Start

# Wait for a service to be readymcp-await port localhost 8080 --timeout 30
# Wait for a file to appearmcp-await file /tmp/deploy.lock --event create --timeout 60
# Wait for a command to succeedmcp-await cmd "curl -sf http://localhost:8080/health" --interval 2 --timeout 30

Tools

All tools accept timeout_seconds (default: 300) and blocking (default: true).

CLI Usage

The binary doubles as a standalone CLI tool:

# TCP portmcp-await port localhost 5432 --timeout 30
# File eventsmcp-await file /var/log/app.log --event modify --timeout 120mcp-await file /tmp/flag --event create --timeout 60mcp-await file /tmp/old.pid --event delete --timeout 30
# HTTP statusmcp-await url https://api.example.com/health --status 200 --timeout 120
# Process exitmcp-await pid 12345 --timeout 300
# Docker container exitmcp-await docker my-container --timeout 600
# GitHub Actions runmcp-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

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:

1. Call wait_for_port with blocking: false
2. Get back immediately:
   json

   {"watch_id": "port-1", "resource": "watch://port-1", "status": "watching"}

3. Do other work while waiting
4. Receive notifications/resources/updated when the condition is met
5. Read watch://port-1 for 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 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:

## 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 buildcargo build --release # release buildcargo test            # run testscargo clippy          # lintcargo fmt             # format

License

MIT