Mcp Await

Name: Mcp Await
Author: ricardo-hdrn

@ricardo-hdrn

Repository

About Mcp Await

Condition watcher for AI assistants — wait for ports, files, URLs, processes, and more

#cli #automation #devops #wait #polling #condition #port #file #url #process #docker #github-actions

Basic information

Config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "await": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-await"
      ]
    }
  }
}

Tools

Cancel an active non-blocking watch by its watch_id.

Wait until a shell command exits with code 0. Re-runs at the specified interval. Use blocking: false for async notification.

Wait until a Docker container exits. Runs `docker wait` under the hood (requires docker installed). Use blocking: false for async notification.

Wait until a filesystem event (create, modify, or delete) occurs on a path. Uses OS-native file watching (inotify). Use blocking: false for async notification.

Wait until a GitHub Actions workflow run completes. Runs `gh run watch` under the hood (requires gh CLI installed). Use blocking: false for async notification.

Wait until a process exits. Monitors /proc/<pid> on Linux. Use blocking: false for async notification.

Wait until a TCP port accepts connections. Use blocking: false to return immediately and get notified via resource update.

Wait until a URL returns an expected HTTP status code. Polls with curl every 2s (requires curl installed). Use blocking: false for async notification.

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.