Use Tapicker Bridge with MCP
MCP exposes Tapicker capabilities as tools an AI agent can discover and call. Start with a working local Bridge and a paired Extension from Getting Started. The browser performs the automation and must remain open.
1. Connect a Local Agent
In your agent's MCP settings, choose stdio, sometimes called a local command. Set the command to tapicker and configure these arguments:
{
"mcpServers": {
"tapicker": {
"command": "tapicker",
"args": ["mcp", "--url", "http://127.0.0.1:9520"]
}
}
}
Configuration formats and file locations vary by agent. Use the same command and arguments in the fields it provides. After saving, reload the MCP connection or restart the agent.
The agent launches tapicker mcp; you do not need to start it in another terminal. This process adapts the agent's stdio connection to an already-running Bridge. Keep the separate tapicker bridge start process running.
If Bridge selected a different port, replace the --url value with its printed HTTP address. The option is optional: explicit --url takes precedence over TAPICKER_BRIDGE_URL, followed by http://127.0.0.1:9520. The adapter does not discover the actual port automatically.
If the agent cannot find tapicker, use its absolute executable path as the command.
2. Verify the Tools
Ask the agent:
Use extension_list to find the ready Tapicker Extension, then workflow_list to list my Workflows. Keep using the selected clientId.
extension_list checks which clients are connected. workflow_list accesses the account signed in to the Extension. If multiple Extensions are ready, select one and pass its clientId on subsequent calls. Pending pairing connections cannot receive commands.
A ready Extension may include a user snapshot. Use user_me to get the latest account information.
To find Workflows for one site, call workflow_list with host: "example.com". host is an exact site filter, without a scheme or path; it may include a port. example.com and www.example.com are different hosts. This excludes generic Workflows whose host is *; use host: "*" to select only those, or omit host for all sites. It works with every scope and can be combined with name; filtering happens before pagination.
The list tool returns summaries identified by id and fullname, without name or nodes. The name input remains a substring filter on fullname. Continue pagination until workflows is empty, and check deletedAt before selecting a Workflow to run or edit. Pass the entry's id as workflowId in later calls. Use workflow_get to read startup argument definitions in workflow.args. With use permission, workflow.nodes is empty because the saved nodes are hidden. With view, edit, or manage permission, it contains the saved nodes.
3. Run and Inspect a Workflow
After choosing one of your Workflows, ask:
Read the startup arguments for WORKFLOW_ID with workflow_get, then use workflow_start and workflow_status_watch. Report the final status and reason. If it fails, inspect workflow_logs and read any truncated entry with workflow_log.
Replace WORKFLOW_ID with the actual ID. If workflow.args declares { "name": "keyword", "type": "string" }, pass args: { "keyword": "Tapicker" } to workflow_start. Use the exact declared names and reuse the same clientId. Supply values for required arguments. Omit an argument to use its configured default. Pass arrays and objects as native JSON values.
workflow_start uses the active browser tab as its starting point. Use-only access is sufficient to run the Workflow. Pass input values in args. Set args.isClearData to the JSON boolean true only to clear existing data in the affected tables.
The start receipt confirms that startup was accepted. Wait for the result with workflow_status_watch, reuse the receipt's clientId and workflowId, and check that runAt matches. An already stopped run returns immediately. At status: "stopped", only reason: "completed" means the Workflow succeeded. If the start response is lost, check status on the same Extension before retrying.
workflow_status reads the latest recorded snapshot from the selected Extension. When present, runAt identifies the run and can be passed to workflow_logs. A snapshot can still describe the previous run while a new one prepares. The tool returns NotFound if the selected Extension has no status record.
timeoutMs optionally limits waiting in milliseconds and returns the latest snapshot with isTimedOut: true. Cancelling the watch also only ends waiting. Use workflow_pause to pause at the next pause point and workflow_resume to continue the same instance. Use workflow_stop to request cancellation of a running or paused instance, then wait for status: "stopped" to confirm cleanup. Pass the workflowId and clientId from the start receipt. Intermediate updates may appear as progress when the agent supports them.
After a run stops, call workflow_status with includeDataSummary: true, the observed runAt, and the same workflowId and clientId. The summary gives table IDs and counts of inserted, updated, and deleted rows, including changes from child Workflows. Use those IDs with data_preview to inspect up to 10 oldest or latest inserted rows without using export quota. Set sample: "latest" to inspect the latest insertions and check isTruncated for size-limited samples. Use data_get when you need more rows. Both tools return registered columnNames and the table’s total rowCount.
Use workflow_logs to read log previews for the latest run. If an entry has detailsTruncated: true, pass its id as logId to workflow_log and reuse workflowId, clientId, and runAt when available. On WorkflowRunChanged, check workflow_status before querying logs again.
4. Generate a Workflow
The connected Extension supplies the authoritative node documentation and schemas. A useful request is:
Read workflow_guide with topic overview. Read the relevant topics from references, get workflow_schema for the nodes you need, and generate a Workflow for my task. Validate it with workflow_validate and repair any issues before creating it. Explain what still needs checking on the actual website.
Use this sequence:
- Read the guide.
workflow_guidedefaults totopic: "overview". Follow a returnedreferences.topicusing the same tool, for examplenodes/print-log. - Get the schema. Pass the node types you plan to use in
nodeTypes, for example["NodeLoop", "NodeExtractData"]; omit it to get the schema for all supported business nodes. The result contains a draft 2020-12 JSON Schema inschema, including the definitions it needs. - Build a document. Pass the parsed clipboard document in
workflow_validate.fragment. - Repair issues.
isValid: falseis a normal tool result. Fix the fields identified bypath,code, and optionalnodeId, then validate again. - Save when ready. Use
workflow_createfor a new private Workflow. Saving and running are separate operations.
For example, workflow_validate accepts:
{
"fragment": {
"format": "tapicker/nodes",
"version": 1,
"nodes": [
{
"id": "hello",
"type": "NodePrintLog",
"config": { "level": "info", "message": "Hello from an agent" }
}
]
}
}
Both clipboard formats use version: 1. Use tapicker/workflow with a workflow object to validate any supplied name, intro, href, or nodes. The object must include at least one of those fields. When validation succeeds, the tool returns normalized nodes if the document includes them. Pass this array directly to create or update. JSON Schema defaults do not fill omitted configuration values.
To create it, call workflow_create with name and nodes, plus optional intro and href. Creation uses the Extension's account and existing permissions and limits. The result includes clientId, workflowId, the full name in workflowName, and revision when supported. Saving and running are separate operations. For href, use an absolute URL (for example, https://example.com, file:///path/to/page.html, or about:blank) or an empty string. To automate a local page, enable Allow access to file URLs in the Extension settings.
Static validation does not prove that selectors match a real page, that the browser is signed in, or that the business result is correct. Observe the actual target page and run the Workflow to verify those parts.
5. Update an Existing Workflow
Use workflow_get with an id from workflow_list to read the latest saved content. Submit workflow.revision unchanged to workflow_update and reuse the returned clientId:
{
"clientId": "c0ffee00-0000-4000-8000-000000000001",
"workflowId": "WORKFLOW_ID",
"revision": 3,
"intro": "Updated by an agent"
}
Replace the example Workflow ID, revision, and client ID with the values you read. At least one of name, intro, href, or nodes is required. Omitted fields are preserved. Set intro or href to an empty string to clear it. A non-empty href follows the same rules as creation. Supplying nodes replaces the entire node tree after validation. Update requires edit or manage permission.
On WorkflowConflict, read the latest content, compare it with the intended changes, reconcile, and submit the revision of that read. The revision in the error only describes the conflict; blindly substituting it can overwrite someone else's changes. There is no force flag. Saving does not change an active run.
If creation times out or its response is lost, call workflow_list with scope: "own" and the requested name in the same Extension, then use workflow_get to verify matching content before retrying. For an uncertain update, read the Workflow first. For an uncertain start, check status first. The requested operation may already have taken effect.
Choose Other Connection Types
The MCP type describes how the agent connects, independently of where Bridge runs:
| Agent connection | MCP type |
|---|---|
Launch tapicker mcp --url http://127.0.0.1:9520 | stdio |
Connect directly to http://127.0.0.1:9520/mcp | Streamable HTTP |
Connect directly to https://bridge.example.com/mcp | Streamable HTTP |
Launch tapicker mcp --url https://bridge.example.com | stdio |
Direct Streamable HTTP
If the agent supports it, select Streamable HTTP and enter the startup MCP Server URL directly. No local tapicker mcp process is needed. For remote access, use HTTPS and configure Authorization: Bearer YOUR_TOKEN in the agent's headers or secret settings. Set up the service using Remote Deployment.
Remote Bridge through stdio
For an agent that only supports stdio, keep the local command configuration and change the arguments:
{
"mcpServers": {
"tapicker": {
"command": "tapicker",
"args": ["mcp", "--url", "https://bridge.example.com"],
"env": { "TAPICKER_BRIDGE_TOKEN": "YOUR_TOKEN" }
}
}
}
Use the agent's secret storage when available. The Token is passed to the adapter; the agent still connects to it over stdio. Reverse-proxy access follows the same distinction.
Which Startup Address to Copy
HTTP: the base address used by--urland HTTP commands.MCP Server: the/mcpendpoint for direct Streamable HTTP connections.WebSocket: the/wsaddress used by the Extension.
For convenience, --url and TAPICKER_BRIDGE_URL accept a copied /mcp endpoint with or without a trailing slash and normalize it to the base address. Other paths, embedded credentials, query strings, and fragments are rejected. Copying /mcp into the adapter configuration still uses stdio.
Tool Reference
All business tools accept optional clientId and return the selected client ID. Tool parameters are flat; there is no HTTP-style input wrapper.
| Tool | Other parameters | Purpose |
|---|---|---|
extension_list | None | Find connected Extensions, with a user snapshot when available |
workflow_guide | Optional topic | Read authoring documentation |
workflow_schema | Optional nodeTypes | Get a self-contained clipboard document schema |
workflow_validate | fragment | Validate without saving or running |
workflow_list | Optional scope, name, host, page, pageSize | List your Workflows |
workflow_get | workflowId | Read metadata, startup arguments, and nodes when permitted |
workflow_create | name, nodes; optional intro, href | Create a private Workflow |
workflow_update | workflowId, revision; at least one editable field | Update saved content |
workflow_start | workflowId; optional args | Start a Workflow |
workflow_pause | workflowId | Pause execution |
workflow_resume | workflowId | Resume execution |
workflow_stop | workflowId | Request a stop |
workflow_status | workflowId; optional runAt, includeDataSummary | Get one status snapshot |
workflow_status_watch | workflowId; optional timeoutMs | Wait for a terminal snapshot or timeout |
workflow_logs | workflowId; optional levels, limit, before, after, runAt | Query latest-run log previews |
workflow_log | workflowId, logId; optional runAt | Read full log details |
data_list | Optional tableName, workflowId, page, and pageSize | Find saved table IDs and column names without using export quota |
data_preview | tableId; optional sample | Preview up to 10 oldest or latest rows without using export quota |
data_get | tableId; optional page, pageSize, or all: true | Read one page or all rows; consumes export quota |
data_export | tableId; optional format | Export the full table as a downloadable file |
data_delete | tableId | Delete the saved table and all its rows |
user_me | No command parameters | Read the current Tapicker account and plan |
If a tool fails, check its error code and message. For a validation result with isValid: false, use issues to fix the reported fields and validate again.
See HTTP for shared field limits, pagination, status reasons, and error codes. The parameter and result meanings are the same across the three interfaces.
Use data_export when you need the full table as a file. Download it from the returned downloadPath on the same Bridge before expiresAt. Use the same Bridge authorization. The file is available for 24 hours, and repeated downloads use no additional export quota. Whether it appears as an attachment depends on the agent.
Troubleshoot the Connection
| Symptom | Check |
|---|---|
| Adapter fails to start | Verify the executable path, Node.js version, and --url |
| Cannot reach Bridge | Keep Bridge running; use its actual port and a reachable address |
Unauthorized | Set the Bridge Token in adapter environment or direct HTTP headers |
SignInRequired | Sign in to Tapicker in the selected Extension |
EmailNotVerified, AccountBanned | Check the Tapicker account status |
NetworkError, RequestTimeout | Check the selected Extension's connection to Tapicker |
ExtensionUnavailable | Pair the Extension and keep the browser open |
ClientIdRequired | List clients and select a ready clientId |
ExtensionCapabilityUnavailable | Use a connected Extension that supports the requested tool |
For lower-level application integration, use HTTP. For server setup, continue with Remote Deployment.