⏱️ timer-mcp

<p align="center"> <img src="https://img.shields.io/badge/MCP-streamable--http-blue?style=for-the-badge" /> <img src="https://img.shields.io/badge/FastMCP-3.x-6c5ce7?style=for-the-badge" /> <img src="https://img.shields.io/badge/Python-3.12-3776AB?style=for-the-badge&logo=python&logoColor=white" /> <img src="https://img.shields.io/badge/Docker-ARM64-2496ED?style=for-the-badge&logo=docker&logoColor=white" /> <img src="https://img.shields.io/badge/AWS-AgentCore-FF9900?style=for-the-badge&logo=amazonaws&logoColor=white" /> </p>

<p align="center"> A minimal MCP server that gives AI agents the ability to <strong>wait</strong>.<br/> One tool. One job. Works locally and on AWS AgentCore Runtime. </p>

---

🤔 The problem it solves

Agents often need to pause between actions — waiting for a resource to become ready, spacing out API calls, or inserting a deliberate delay in a workflow. Without a timer tool, an agent has no way to wait.

A naive implementation that holds the HTTP connection open for the full duration fails on AgentCore: the platform's sidecar proxy enforces a hard ~60 second timeout on individual MCP tool calls, returning:

MCP error -32001: Request timed out

---

⚙️ How it works

The server caps MAX_DURATION at 55 seconds per call when running on AgentCore — safely under the proxy limit. For longer waits the agent calls the tool multiple times sequentially, which it works out automatically from the tool description:

wait(55)  →  "Waited 55 second(s)."
wait(35)  →  "Waited 35 second(s)."
              ──────────────────────
              total: 90s across 2 calls

Locally there is no proxy, so the default MAX_DURATION of 840 seconds applies and a single call can hold for up to 14 minutes.

---

🛠️ Tool reference

Tool	Argument	Description
wait	seconds: int	Pause for the specified duration (capped at MAX_DURATION). For longer waits, call multiple times sequentially.

---

🔧 Environment variables

Variable	Default	Description
HOST	0.0.0.0	Bind address
PORT	8000	Listen port
MAX_DURATION	840	Max seconds per call. Set to 55 on AgentCore.

---

🐳 Run locally

Start the server

docker build -t timer-mcp .
docker run -p 8000:8000 timer-mcp

Server is available at http://localhost:8000/mcp.

---

🔌 Connect to your MCP client

Add the following to your MCP client config and restart:

{
  "mcpServers": {
    "timer": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

Client	Config file
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json
Claude Code	~/.claude/mcp.json (global) or .claude/mcp.json (project)
Cursor	~/.cursor/mcp.json (global) or .cursor/mcp.json (project)
VS Code	~/.vscode/mcp.json (global) or .vscode/mcp.json (project)

---

🧪 Smoke test

# Initialize a session
SESSION=$(curl -si -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.1"}}}' \
  | grep -i 'mcp-session-id' | awk '{print $2}' | tr -d '\r\n')

# Call wait(5) — should take ~5s and return "Waited 5 second(s)."
time curl -s -N -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: $SESSION" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"wait","arguments":{"seconds":5}}}'

---

☁️ Deploy to AWS AgentCore

Prerequisites

• Docker with buildx (ARM64 support)
• AWS CLI with a profile that has ECR and AgentCore permissions
• An ECR repository (timer-mcp)
• An AgentCore execution role with ECR pull access

1. Push the image to ECR

Uncomment the ECR authentication block in deploy.sh, then run:

bash deploy.sh

This builds the ARM64 image and pushes it to:

<account-id>.dkr.ecr.us-east-1.amazonaws.com/timer-mcp:latest

2. Create the AgentCore runtime

aws bedrock-agentcore-control create-agent-runtime \
  --region us-east-1 \
  --agent-runtime-name "timer_mcp" \
  --agent-runtime-artifact '{
    "containerConfiguration": {
      "containerUri": "<account-id>.dkr.ecr.us-east-1.amazonaws.com/timer-mcp:latest"
    }
  }' \
  --role-arn "arn:aws:iam::<account-id>:role/<execution-role>" \
  --network-configuration '{"networkMode": "PUBLIC"}' \
  --protocol-configuration '{"serverProtocol": "MCP"}' \
  --environment-variables '{"HOST":"0.0.0.0","PORT":"8000","MAX_DURATION":"55"}' \
  --authorizer-configuration '{
    "customJWTAuthorizer": {
      "discoveryUrl": "https://cognito-idp.<region>.amazonaws.com/<pool-id>/.well-known/openid-configuration",
      "allowedClients": ["<client-id>"]
    }
  }'

3. Update an existing runtime

AgentCore pulls the image fresh on every invocation — pushing a new latest tag to ECR is enough for code changes, no runtime update needed.

To update environment variables:

aws bedrock-agentcore-control update-agent-runtime \
  --agent-runtime-id <runtime-id> \
  --region us-east-1 \
  --agent-runtime-artifact '{"containerConfiguration":{"containerUri":"<account-id>.dkr.ecr.us-east-1.amazonaws.com/timer-mcp:latest"}}' \
  --role-arn "arn:aws:iam::<account-id>:role/<execution-role>" \
  --network-configuration '{"networkMode":"PUBLIC"}' \
  --protocol-configuration '{"serverProtocol":"MCP"}' \
  --environment-variables '{"HOST":"0.0.0.0","PORT":"8000","MAX_DURATION":"55"}'

---

⚠️ AgentCore proxy timeout

This limitation does not apply to local Docker runs.

AgentCore's sidecar proxy enforces a hard ~60 second per-request timeout on MCP tools/call requests. This is not configurable via lifecycleConfiguration (which only governs session/microVM lifetime). Any wait call exceeding this receives MCP error -32001: Request timed out.

Setting MAX_DURATION=55 on the runtime leaves a 5-second safety margin. The agent chains calls automatically for longer waits:

Total wait	Calls
≤ 55s	1
56s – 110s	2
111s – 165s	3
N seconds	ceil(N / 55)