await-mcp

Block agent execution until a condition is met — no more sleep N loops or returning early.

Problem

When agents run long operations (cloud builds, CI tests, deployments), they either:

1. sleep N then check — inaccurate, wastes turns, model may give up
2. Return and let the user remind them — breaks automation

Solution

An MCP server that provides blocking await tools. The agent calls a tool, and the MCP server blocks (polling internally) until the condition is met. The agent is "stuck" on the tool call until it returns.

Agent: Start build → build ID 12345
Agent: Wait for build → await_command("curl -sf .../build/12345 | grep -q done") → BLOCKS
  [progress] Check #1 (0s): exit=1, running...
  [progress] Check #2 (30s): exit=1, running...
  [progress] Check #3 (60s): exit=0, success!
Agent: Build succeeded! Proceeding...

How It Works

Key insight: MCP tool calls are blocking

MCP clients block on MCP tool calls — the agent loop awaits the tool result. The MCP server can hold the connection open as long as needed (up to the configured timeout).

Progress notifications

The client generates a progressToken for each MCP tool call and listens for notifications/progress. The server sends progress updates with this token, so the user sees real-time polling status in the UI.

Timeout configuration

Level	Default	Configurable via
MCP server (connection-level)	client-dependent	timeout in the client's MCP server config
Per-tool-call	1 hour (3600s)	timeout_seconds parameter in the tool call

Set a large connection-level timeout in your client config to allow very long operations.

Tools

await_command

Polls a shell command until it exits with code 0 (success) or 2 (failure).

• Exit 0: condition met → return { status: "success" }
• Exit 2: condition failed → return { status: "failed" }
• Other exit code: still running → keep polling
• Timeout: return { status: "timeout" }

{
  "command": "curl -sf https://ci.example.com/build/123/status | grep -q done",
  "timeout_seconds": 3600,
  "interval_seconds": 30
}

await_url

Polls a URL until it returns the expected HTTP status code.

{
  "url": "http://localhost:3000/health",
  "expected_status": 200,
  "body_contains": "ready",
  "timeout_seconds": 600,
  "interval_seconds": 10
}

await_file

Waits for a file to exist (and optionally contain specific content).

{
  "path": "/tmp/build-status",
  "contains": "SUCCESS",
  "timeout_seconds": 3600,
  "interval_seconds": 10
}

Installation

1. Clone and install dependencies

git clone https://github.com/adlternative/await-mcp.git
cd await-mcp
npm install

Requires Node.js 18+ (uses the built-in global fetch).

2. Register the MCP server with your client

Replace /path/to/await-mcp with the absolute path where you cloned the repo.

opencode

Add to your opencode.json (project) or ~/.config/opencode/opencode.json (global):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "await": {
      "type": "local",
      "command": ["node", "/path/to/await-mcp/server.mjs"],
      "enabled": true
    }
  }
}

See the opencode MCP docs for more options.

Claude Code

Register via the CLI:

claude mcp add await -- node /path/to/await-mcp/server.mjs

Or add it manually to your .mcp.json (project scope) or ~/.claude.json:

{
  "mcpServers": {
    "await": {
      "command": "node",
      "args": ["/path/to/await-mcp/server.mjs"]
    }
  }
}

Qoder CLI

Add to ~/.qoder/settings.json:

{
  "mcpServers": {
    "await": {
      "command": "node",
      "args": ["/path/to/await-mcp/server.mjs"],
      "cwd": "/path/to/await-mcp",
      "timeout": 7200000,
      "alwaysAllow": ["await_command", "await_url", "await_file"]
    }
  }
}

• timeout: 7200000 — 2 hour max per tool call (overrides the default)
• alwaysAllow — skip permission prompts for the await tools

Usage Examples

Cloud build

Use await_command to wait for the build to complete:
  command: "curl -sf https://ci.example.com/build/<id> | jq -e '.status == \"success\"' && exit 0 || exit 1"
  interval_seconds: 30
  timeout_seconds: 3600

Service health check

Use await_url to wait for the service to be ready:
  url: "https://my-service.example.com/health"
  expected_status: 200
  interval_seconds: 10
  timeout_seconds: 600

File-based signaling

Use await_file to wait for a status file:
  path: "/tmp/deploy-status"
  contains: "SUCCESS"
  interval_seconds: 5
  timeout_seconds: 1800

Architecture

┌──────────────┐     MCP (stdio)      ┌──────────────┐
│  MCP client  │ ◄──────────────────► │   await-mcp  │
│  (agent)     │                      │   (server)   │
│              │  tools/call ──────►  │              │
│   agent      │                      │  poll loop   │
│   blocked    │  ◄─ progress notif   │  run check   │
│   waiting    │                      │  sleep       │
│              │  ◄─ result ────────  │  return      │
│   continues  │                      │              │
└──────────────┘                      └──────────────┘

Why not just sleep?

• sleep N is a guess — too short and you check too early, too long and you waste time
• Each check is a separate agent turn, consuming tokens and risking the model giving up
• await-mcp does the polling inside the MCP server, not in the agent loop

Future Improvements

• await_webhook: Two-phase (register + wait) for push-based notifications from CI/CD
• WebSocket support: For real-time push instead of polling
• Composite conditions: Wait for multiple conditions (AND/OR)

License

MIT