Get Started with Tapicker Bridge

This guide sets up Bridge on the same computer as your browser. By the end, you will have run a Workflow from your terminal and connected an AI agent through MCP.

1. Install the Requirements

Install Node.js version 22 or later. Its installer includes npm, which you will use to install Bridge. Open a terminal and check both commands:

node --version
npm --version

If a command is unavailable after installation, reopen your terminal. The Node.js version should start with v22 or a higher major version.

Install the Tapicker Extension, open it, and sign in to your Tapicker account. Keep the browser open for the following steps.

2. Install Bridge

Install the CLI globally:

npm install --global @tapicker/bridge

Check that the tapicker command is available:

tapicker --version

If your terminal cannot find it, reopen the terminal and check that npm's global executable directory is in your PATH.

3. Start Bridge

Start Bridge in the foreground:

tapicker bridge start

Keep this terminal open. To run Bridge in the background instead, use tapicker bridge start --daemon; you can close the terminal and stop the service later with tapicker bridge stop.

Startup output includes addresses like these and a four-digit pairing code:

HTTP: http://127.0.0.1:9520
WebSocket: ws://127.0.0.1:9520/ws
MCP Server: http://127.0.0.1:9520/mcp
Pairing Code: 1234

Use the code from your own terminal; 1234 is only an example. Each address has a purpose:

Startup labelUse it for
HTTPCLI --url and HTTP API requests
WebSocketThe Extension's Bridge connection
MCP ServerAn agent connecting directly with Streamable HTTP

Bridge tries ports 9520 through 9530. If it prints a different port, use that actual address in all later examples. There is no automatic port discovery in the CLI or MCP adapter.

4. Connect the Extension

  1. Open Tapicker and go to Settings > General.
  2. Turn on Bridge.
  3. Click Scan to find the local Bridge. Alternatively, enter the printed WebSocket address and click Connect.
  4. Enter the four-digit pairing code when prompted.
  5. Wait for the connection status to show Connected.

Open a second terminal and check the connection:

tapicker bridge extensions

Your Extension should appear with ready: true. Run the same check after restarting Bridge to confirm the Extension has reconnected.

Signing out disconnects the Extension from Bridge. Your Bridge settings are saved, so the Extension reconnects automatically when you sign in and open it again.

If pairing is locked, run tapicker bridge code --refresh on the Bridge computer, then use the new code.

5. Run Your First Workflow

Choose a Workflow to run. If you do not have one, find a suitable Workflow under Shared with Me in the Extension, or create your own.

In the Extension's Workflow list, open the Workflow's menu and choose Copy ID. Replace WORKFLOW_ID below with that value:

tapicker workflow start WORKFLOW_ID --watch

If Bridge selected 9521, for example, specify its address:

tapicker workflow start WORKFLOW_ID --url http://127.0.0.1:9521 --watch

The command prints a start receipt followed by status updates. Wait for status: "stopped" and inspect reason: completed means the Workflow finished successfully. A start receipt alone does not mean execution is complete.

Pressing Ctrl+C in this second terminal stops waiting. To stop the Workflow itself, use tapicker workflow stop WORKFLOW_ID, with the same --url if needed.

6. Add Tapicker to Your Agent

In your agent's MCP settings, choose stdio (sometimes shown as a local command). Configure it to launch tapicker with these arguments:

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

Use your Bridge's actual HTTP address for --url. Configuration file locations vary by agent; use the example's command and arguments in the fields your agent provides.

Restart or reload the agent's MCP connection. The agent starts tapicker mcp automatically; you do not need to run that command in a separate terminal. The Bridge process from step 3 must still be running.

Ask the agent:

List the connected Tapicker Extensions using extension_list, then list my Workflows using workflow_list. Do not run or change anything yet.

The first call checks connectivity; the second checks that the connected Extension can access your account's Workflows. When those succeed, ask it to start the Workflow you selected and wait for its result.

If the agent cannot find tapicker, use the executable's absolute path for command.

If your agent supports Streamable HTTP, you can instead connect directly to the printed MCP Server URL without a local adapter. For clients using mcpServers and type: "http", the configuration is:

{
  "mcpServers": {
    "tapicker": {
      "type": "http",
      "url": "http://127.0.0.1:9520/mcp"
    }
  }
}

Use your actual MCP Server address. Your agent may use a different configuration format or offer a URL field in its settings. See MCP for both setup types.

Stop and Continue Later

For a foreground Bridge, press Ctrl+C in the original terminal to stop the service. If you used --daemon, run tapicker bridge stop. To use Tapicker through Bridge later, start Bridge again and check that the Extension reconnects.

For background operation, custom connection settings, and troubleshooting, continue with CLI. For application requests, read HTTP. For agent configuration and Workflow generation, read MCP. Use Remote Deployment when the Bridge and its clients run on different computers.