agent-pocket-mcp

MCP server for Agent Pocket — a remote human-in-the-loop bridge for AI agents.

Lets AI agents (Cursor, Windsurf, Claude, Cline, Copilot) send approval requests, questions, and notifications to you on your phone via a PWA with push notifications, then block until you respond.

Agent (MCP tool call) → Agent Pocket Server → Push / Slack / Email → Your phone
                                                                           ↓
Agent unblocks ←──────────────────────────────────── Approve / Answer / Done

Installation

No installation needed — use directly via npx:

{
  "mcpServers": {
    "agent-pocket": {
      "command": "npx",
      "args": ["-y", "agent-pocket-mcp@latest"],
      "env": {
        "APPROVAL_SERVER_URL": "https://agent-from-pocket-production.up.railway.app",
        "APPROVAL_API_KEY": "<your-api-key-from-dashboard>"
      }
    }
  }
}

Or install globally:

npm install -g agent-pocket-mcp

Environment variables

| Variable | Description | |---|---| | APPROVAL_SERVER_URL | URL of your Agent Pocket server | | APPROVAL_API_KEY | Per-user API key from the dashboard (Settings → API Key) | | APPROVAL_TIMEOUT_SEC | Optional — auto-timeout requests after N seconds |

Tools

request_approval — Gate destructive actions

Blocks until you approve or reject. Use before any irreversible action.

Returns: "approved" or "rejected"

{ "message": "Deploy to production?", "context": "branch: main, commit: abc123" }

ask_question — Get information only you know

Blocks until you type an answer.

Returns: Your text answer (string)

{ "message": "Which S3 bucket should I upload to?", "context": "staging or production?" }

request_manual_step — Delegate UI/physical steps

Blocks until you mark it done or skip.

Returns: "done" or "skipped"

{ "message": "Click 'Authorize' in the OAuth popup", "context": "https://example.com/oauth" }

notify — Non-blocking status updates

Returns immediately — does not block the agent.

Returns: "Notification sent"

{ "message": "Build complete — 42 tests passed", "context": "Duration: 3m 12s" }

Agent Setup Tools

init_pocket_agent

Injects Agent Pocket usage rules into your project's AI agent config files. Run once per project.

{ "project_path": "/path/to/your/project", "targets": ["windsurf", "cursor"] }

Supported targets: cursor, windsurf, claude, copilot, cline

init_agent_polling

Adds task-polling rules for agent tabs. Run in addition to init_pocket_agent if this IDE tab acts as a background agent.

Agent Polling Tools

For AI agent tabs that should receive and execute tasks assigned from the dashboard.

register_as_agent

One-time registration for an IDE tab. Returns { agentId, name }.

{ "ideType": "windsurf" }

poll_for_task

Blocks until a task is assigned from the dashboard. Returns the task object or { terminated: true }.

{ "agentId": "<id-from-register>" }

complete_task

Marks a task as done after execution.

{ "taskId": "<id-from-poll_for_task>" }

Getting an API Key

1. Sign in to the Agent Pocket PWA
2. Click the key icon (🔑) in the top-right corner
3. Copy the key — treat it like a password

Links

• Agent Pocket dashboard
• Full documentation
• npm package