Dicey Table
Docs
Search the docs

Reference

Bridge command line reference

Every command, flag and environment variable of the DiceyTable MCP bridge, plus the ports it uses, where it keeps your key, and how versions work.

2 min readVerified

View as Markdown
On this page7 sections

The bridge is the small program that links your AI agent to a DiceyTable tab. Its npm package is @diceytable/mcp-bridge, and the command it installs is diceytable-mcp-bridge. With npx, run it like this:

Shell
npx -y @diceytable/mcp-bridge@1 [command] [options]

Your MCP client starts the bridge for you, so most people only ever type login and doctor. This page lists everything else for when you need it. To set the bridge up the first time, see install the DiceyTable MCP bridge.

Commands#

Command What it does
(none), or serve Runs the MCP server over stdio. Your MCP client starts this; you never run it by hand. It stops when the client closes its input.
login Reads an access key at a hidden prompt, or from the first line of input (echo dtpat_… | npx -y @diceytable/mcp-bridge@1 login). It checks the key with DiceyTable and saves it for the API in --api. Then it prints the account, the key's name, its permissions and its expiry date. Exits with status 1 if the key is malformed or refused.
logout Removes the saved key for --api, or every saved key with --all. Warns you if DICEYTABLE_TOKEN is still set.
status Shows which key is in use (its name and first characters, never the whole key), where it came from, the account, and whether a hub is running on --port.
doctor Checks your Node.js version, each hub port, the key, whether the API answers, your clock, and the allowed folders. Then it prints browser hints. Exits with status 1 when any check fails.
help, --help, -h Prints usage, every flag and every environment variable.
version, --version, -v Prints the bridge version.

An unknown command or flag prints an error and exits with status 2.

Flags#

A flag that takes a value accepts --flag value or --flag=value. A flag on the command line wins over its environment variable.

Flag Environment variable Default What it does
--port <n> DICEYTABLE_BRIDGE_PORT 47621 The hub port on your computer. If another program holds it, the bridge tries the next one, up to 47625. The site can reach only 47621 to 47625, so a port outside that range never connects. doctor warns about it.
--relay off Use only DiceyTable's relay server. The bridge opens no hub on your computer.
--no-relay off Never open the relay. Tabs must reach the hub on your computer, so Safari can't pair. You can't pass both --relay and --no-relay.
--dev off Also accept tabs from a local development site (http://127.0.0.1:5173 and http://localhost:5173), and point the connect link at that site. Unless you pass --api or set DICEYTABLE_API, it also switches the API to http://127.0.0.1:8787.
--allow-origin <origin> Also accept tabs from this exact origin, such as a preview build (https://pr-12.onrender.com). Repeatable. It must be a bare origin with no path, query or password. It must use https, except http for a loopback address.
--allow-dir <dir> Also allow local files in this folder, for asset_import with localPath and for screenshot saveTo. Repeatable. A relative path starts from the working folder. The folder your MCP client started in is always allowed.
--api <url> DICEYTABLE_API https://api.diceytable.com (http://127.0.0.1:8787 with --dev) The DiceyTable API address. It must use https, except http for a loopback address. Keys are saved per API, so login with a different --api saves a separate key.
--client-name <name> your MCP client's own name The agent name DiceyTable shows in the consent dialog, the indicator and Settings. The bridge keeps the first 64 characters. The AI badge other players see shows at most 32.
--log-level <level> DICEYTABLE_LOG_LEVEL info silent, error, warn, info or debug. Logs go to stderr only, because stdout carries the MCP messages.
--all For logout only: remove the keys for every API.
--help Same as the help command.
--version Same as the version command.

Environment variables#

Variable Meaning
DICEYTABLE_TOKEN Your access key (dtpat_…). It wins over the saved key, except for a loopback API (127.0.0.1 or localhost). There it is not sent unless DICEYTABLE_TOKEN_ALLOW_DEV=1, so a real key never goes to whatever program is listening on that port. Set it through your client's variable syntax, never as plain text in a shared config. See API keys.
DICEYTABLE_TOKEN_ALLOW_DEV 1 lets DICEYTABLE_TOKEN be sent to a loopback API. Leave it unset unless the key really belongs to that local server.
DICEYTABLE_BRIDGE_PORT Same as --port.
DICEYTABLE_API Same as --api.
DICEYTABLE_LOG_LEVEL Same as --log-level.

Where does the bridge save my key?#

login saves one key per API address in a credentials file:

System File
Windows %APPDATA%\diceytable\credentials.json
macOS and Linux ~/.config/diceytable/credentials.json (or under $XDG_CONFIG_HOME if you set it). Only your user can read the file or its folder.

The bridge writes nothing else to disk, except images you ask it to save with saveTo.

Which ports does the bridge use?#

Bridge hub and ports The first bridge holds 127.0.0.1 port 47621 and becomes the hub. Later bridges connect through the hub as relay clients. Tabs scan ports 47621 to 47625 to find the hub. If the direct path is blocked, a dashed fallback runs through wss://api.diceytable.com/agent-relay. Your computer bridge 2relay client bridge 3relay client bridge 1: hub127.0.0.1:47621first to start tab/editor tab/table tabs scan 47621 to 47625 Each MCP app starts its own bridge. If the hub closes, another bridge takes the port; tabs reconnect. relay (fallback)wss://api.diceytable.com/agent-relay fallback
Ports. The first bridge becomes the hub; the rest share it.
Connection Direction What it is for
ws://127.0.0.1:47621 (to 47625) Tabs connect in The hub. It listens on 127.0.0.1 only, so other computers can't reach it. It checks every tab's origin against an exact list. Messages are capped at 8 MB.
https://api.diceytable.com/api/agent/* The bridge connects out Checking your key, starting and ending a session, a heartbeat every 30 seconds, and URL imports.
wss://api.diceytable.com/agent-relay The bridge connects out The relay. It opens once a session exists, unless you pass --no-relay. Messages are capped at 2 MB, so screenshots shrink to about 400 KB over it.

Several bridges at once. Every MCP client runs its own bridge. The first one to need the port becomes the hub. Each later bridge checks that the port really belongs to a DiceyTable hub, then connects through it as a relay client. If the hub's client closes, the others race to take over the port in under a second, and tabs reconnect by themselves. No bridge outlives its MCP client. How the bridge works explains the hub and the relay in plain words.

Which bridge version do I need?#

Any 1.x bridge works with the site today. @1 in the npx line always fetches the newest 1.x release.

  • The npm major version (@1) matches the major version of the protocol the bridge and the site speak. If they don't match, the tab says "Your DiceyTable bridge is too old" (or too new) and names the npx line to run.
  • Smaller protocol additions are agreed when the tab connects, so any 1.x bridge works with any 1.x site.
  • Tools are matched by name. If the site has a tool your bridge doesn't know, the agent can still reach it with page_call_tool. If your bridge lists a tool the site lacks, the call returns tool-unavailable and names the site version it needs.
  • After a new major version ships, the site keeps accepting the old one for at least 90 days.
  • Each release's changes are in the package's CHANGELOG.md.

Did this page answer your question?