Connect an AI Agent to Tapicker Bridge

Bridge exposes Tapicker commands as MCP tools and as an HTTP API. In both cases, Bridge must already be running and at least one paired Extension must be ready.

Choose MCP or HTTP

  • MCP is usually the easiest option for an AI agent that supports MCP. The agent discovers named tools such as workflow_start and workflow_pause.
  • HTTP is a good fit for scripts, services, or agents that already make REST requests.

Both interfaces use the same Workflow and data commands. Neither starts a second Bridge server.

Connect with MCP

For a local agent, configure an MCP server that launches the installed tapicker CLI:

{
  "mcpServers": {
    "tapicker": {
      "command": "tapicker",
      "args": ["mcp"],
      "env": {
        "TAPICKER_BRIDGE_URL": "http://127.0.0.1:9520"
      }
    }
  }
}

Restart or reload the agent after saving its MCP configuration. If Bridge chose a different port, set TAPICKER_BRIDGE_URL to the HTTP address shown at startup. When a Bridge Token is configured, also set TAPICKER_BRIDGE_TOKEN in the MCP server environment.

The tapicker mcp process is an adapter: it connects to an already-running Bridge over HTTP and exposes MCP over stdio to the agent.

For an agent that supports remote Streamable HTTP MCP, use the Bridge endpoint https://<host>:<port>/mcp. Remote deployments require TLS and a Bearer Token; see Remote Deployment.

Available tools include:

ToolPurpose
extensions_listFind connected Extensions and their clientId values
workflow_start, workflow_pause, workflow_resume, workflow_stopControl a Workflow
workflow_status, workflow_status_watchGet one status snapshot or wait for updates
workflow_logs, workflow_logQuery log previews or read full details for a selected log
data_get, data_deleteRead or delete an extracted data table

Call the HTTP API

List connected Extensions:

curl http://127.0.0.1:9520/v1/extensions

Start a Workflow:

curl -X POST http://127.0.0.1:9520/v1/commands/workflow.start \
  -H 'Content-Type: application/json' \
  -d '{"input":{"workflowId":"jr657xeb","args":{"keyword":"Tapicker"}}}'

Pause, resume, stop, and status use the same command endpoint pattern, for example:

POST /v1/commands/workflow.pause
POST /v1/commands/workflow.resume
POST /v1/commands/workflow.stop
POST /v1/commands/workflow.status

When a Bridge Token is configured, send Authorization: Bearer <token> with protected requests. The full endpoint list and request format are in the API Reference.

Select the Target Extension

An optional clientId selects a target Extension. Omit it only when exactly one ready Extension is connected. If multiple are ready, get their IDs from GET /v1/extensions or the MCP extensions_list tool, then pass the chosen clientId with the command.

Commands are routed to one Extension; Bridge does not broadcast them to every browser.

Monitor Long-Running Workflows

workflow_start returns when the start request is accepted. To wait for the result, use the MCP workflow_status_watch tool or connect to the Workflow status WebSocket. The HTTP workflow.status command is a one-time snapshot, not a polling subscription. A successful watch reports the execution result; only reason: "completed" means the Workflow succeeded. If a start response times out or the connection closes, query workflow_status before retrying because the Workflow may already be running.

Reading a data table returns all rows and consumes the connected Extension account’s export quota. Deleting a table removes it from Tapicker Data; verify the tableId before calling data_delete.

Investigate Logs on Demand

Use workflow_status_watch to wait for execution. If a run fails or progress needs investigation, query workflow_logs, optionally filtering to ["warn", "error"]. Do not continuously poll logs. If a record has detailsTruncated: true, call workflow_log with its workflowId and logId to read the full readable details.

Only the latest run is retained. Both queries return runAt; you may pass it into subsequent calls to reject a different run with WorkflowRunChanged, but it is optional. Log queries do not determine success: use terminal status and reason. See Workflow logs reference for filtering, pagination, and response fields.