Dub MCP Server & CLI

What is the Dub MCP server & CLI?

The Dub MCP server & CLI is a free, open source program that lets AI agents read and change requested Dub link and partner data with explicit approval for you, in 2 ways. The MCP server is what an AI app like Claude, Codex or Cursor connects to, through MCP (Model Context Protocol), the open standard AI apps use to call outside tools.

You ask in plain language. Your AI picks the right tool, and the server makes the call to the fixed Dub REST API origin using the selected private workspace key.

The CLI is the same program as commands. dub-cli list-links runs the same code your AI runs when you deliberately read the intended workspace page, whether an agent like Claude Code runs it or you do.

What can you ask it?

Once it's set up, you ask the way you'd ask an assistant. These are real prompts it handles:

Try asking
Find these workspace links and inspect one exact ID.
Create only the slug/destination I approve.
Review this ordered link/tag work and show its exact approval hash.
Submit only that matching approved batch.
Read the requested partner application and eligible analytics.
Save this QR or temporary embed credential into a new private file.

Dub already offers official hosted Links/Partners MCPs, an official task CLI, native bulk operations and scoped/read-only workspace keys. This owned companion adds verified shared local policy, exact ordered request review and private generated-credential delivery; current alternatives are compared below.

How to install the Dub MCP server

Choose the shared task CLI, local stdio MCP or versioned desktop bundle in the existing controls. Codex comes first, with full client/OS setup below.

Set up Dub access

Private workspace access

1. Sign into the intended Dub workspace. Open Settings → API Keys / tokens. Verify the workspace before copying a key.
2. Create only the needed all-access, read-only or restricted link/analytics/domain/tag permissions. REST keys are workspace-specific; native read-only and workspace isolation already exist in Dub.
3. Store the key outside repositories as DUB_API_KEY in private user settings or DUB_TOKEN_FILE pointing to an absolute token-only file. On macOS/Linux use a private 0700 directory and 0600 regular non-symlink file, at most 64 KiB. On Windows restrict ACLs to yourself; POSIX mode checks do not verify ACLs.
4. Run dub-cli doctor for local settings. Deliberately run doctor --network for one GET /links?pageSize=1; it reports the returned count without echoing the link. This proves that read, not workspace ownership or every permission.
5. Discover actual link IDs and fields, review the requested change, and approve only that operation or matching reviewed batch. Do not delete links, register domains, track sales or change financial records just to test installation.

REST keys are sent only to https://api.dub.co as Authorization: Bearer. The official hosted MCP accepts OAuth or the documented Mcp-Dub-Token header; do not substitute that header for REST Bearer. Official dub CLI OAuth uses its own private session and scopes. This wrapper never imports those sessions, starts OAuth, loads .env, purchases access or saves a key through login. login prints private setup instructions only.

DUB_ACCOUNTS is a private array of unique {name,api_key,token_file} profiles. A token file overrides only that selected profile's key and caches until process restart. Profiles never fall back to DUB_API_KEY or another account when credentials are missing. Labels do not verify provider ownership. A tenantId filter is customer segmentation within a workspace, not another workspace's authentication.

Plans, quotas and provider effects

The AGPL wrapper is free. Dub subscription limits, partner-program eligibility, domain-registration charges, conversions and financial actions remain provider costs and permissions. Check current plans and API limits.

Documented standard per-key limits are Free 60/minute, Pro 600/minute, Business 1200/minute and Advanced 3000/minute; Enterprise is custom. Analytics/events additionally list Free unavailable, Pro two requests/second, Business four/second and Advanced eight/second. Successful installation does not unlock paid analytics. The default 1100 ms process-wide request-start spacing is conservative for one Free key; other processes/apps share its quota. It is not a guaranteed limiter for all plans or concurrent clients.

No request automatically retries, including 429, redirects, timeouts or 5xx. Respect Retry-After before deliberately repeating a read. Inspect actual provider state before repeating an unknown mutation. Requests are capped at 1 MiB and responses at 5 MiB. Each explicit list call reads one native page: links/customers/commissions support mutually exclusive startingAfter/endingBefore cursors; other families use their documented page/pageSize or limit. Deprecated page parameters remain marked, cannot be mixed with cursors, and require positive integers. There is no invented all_pages option or complete-backup claim.

Native bulk link creation/update/deletion already supports up to 100 items. Bulk create omits custom previews and webhook events, and HTTP 200 can mix successful links with per-link errors. The local reviewed batch is a separate ordered one-to-twenty link/tag/folder workflow, with all payloads checked and exact approval hash before first request. A bulk task can still affect up to 100 records; twenty tasks is not a twenty-record budget.

Domain deletion is irreversible and deletes its links. Partner ban cancels commissions and deletes links; financial changes and customer deletion need explicit user intent. create_commission can return HTTP 202 with a task receipt: acceptance is not completed financial work. Tracking events can affect analytics and commissions. No payout execution endpoint is invented.

Rotation and revocation

Revoke the intended key in the correct workspace, replace private settings/files and restart every process. Native key/user role changes apply at the provider; machine-user keys share their owner's permissions and deleting a machine user revokes its keys. Do not create a machine user merely to test this package. Revoke official OAuth integrations separately. Removing npm/client entries does not revoke keys, undo links/events/commissions, refund a registered domain or remove saved private output files.

Check that it works

Start with local discovery/settings, then deliberately opt into one links read.

dub-cli --version
dub-cli doctor
dub-cli list-accounts --agent
dub-cli doctor --network

dub-cli --version
dub-cli tools
dub-cli list-accounts --agent
dub-cli doctor
dub-cli doctor --network
dub-cli list-links --page-size 1 --account work --agent

Local doctor reports profile count/default/policy without loading credentials or claiming authentication. --network opts into exactly one read, with count only. Actual account role/ownership, analytics plan, every endpoint and writes remain separate checks. Never use a destructive or paid call as an install test.

Use the Dub CLI

The CLI is the same 61 tools as commands. AI agents that run commands, like Claude Code, Codex and OpenCode, use it on their own, and you can type the same commands in a terminal or a script.

Every tool name becomes a command with dashes, so list_links runs as dub-cli list-links.

dub-cli tools
dub-cli list-links --help
dub-cli schema create-link
dub-cli list-links --page-size 5 --account work --agent
dub-cli get-link --link-id YOUR_LINK_ID --account work --agent

The bare dub-cli lists every command, and dub-cli <command> --help shows what a command takes. All 39 mutations/private-output writes require --confirm. --agent/--yes never approve work. Repeat --tasks with individual JSON objects; native array bodies can use an absolute private payload_file.

These flags work on every command:

A script can branch on the exit code:

MCP server or CLI: which one?

Both surfaces call the same tools. Codex can connect to the local MCP server or run the CLI directly. Neither requires Claude Code.

MCP provides structured tool discovery; the CLI supports scripts, compact JSON, field selection and command/schema discovery. Official hosted MCP connection and local CLI authentication have different setup requirements.

Codex-specific token measurements are pending. Record the actual client/model versions, discovery configuration, input/output usage, caching, latency and equivalent successful outcomes. Standing definitions and full task cost are separate measurements; CLI commands, selected help, results and reasoning still consume tokens.

No efficiency percentage or Claude-derived figure is presented as a Codex result. Other-client benchmarks can be added separately.

Link and partner workflows

Inspect and approve the intended link

Use list_links and get_link with a real link_id, external_id or domain plus key. API external-ID queries require the documented ext_ prefix. Existing get_link_stats now reaches the current analytics endpoint, with event/group/filter/date fields; it does not imply analytics is on the Free plan. Use schema/help to inspect native UTM, conversion tracking, expiration, tags/folders, A/B variants and platform redirect fields before submitting.

create_link/upsert_link require url; update_link must include an actual change. PATCH semantics follow the provider, not a recursive merge invented by this package. A/B/native nested constraints come from the pinned current schema. Native bulk create accepts an array, bulk update a data object, and bulk delete comma-separated linkIds. No bulk custom previews or webhook events are invented.

Partners, applications and financial work

Current list_program_applications/approve_program_application/reject_program_application use /program-applications. The older published SDK snapshot uses /partners/applications; do not assume aliases. Read the requested application/partner before approving or rejecting. Ban/delete actions can cancel commissions or remove links; confirmation must match the user's intended scope.

create_commission accepts the documented discriminated custom/lead/sale bodies and may return an asynchronous task receipt. bulk_update_commissions only accepts its native pending/refunded/duplicate/canceled/fraud statuses; do not fabricate an approved/paid status. list_payouts reads provider records; no payout transfer endpoint exists here. Events/conversions can affect business metrics and affiliate commissions, so they require the same explicit guard as other POSTs. No polling, financial completion, refunds or unrelated messages occur implicitly.

Requested private QR and embed output

dub-cli get-qr-code --url https://example.com/requested --output-file /absolute/private/requested.png --confirm --agent
dub-cli create-referrals-embed-token --payload '{"partnerId":"YOUR_PARTNER_ID"}' --output-file /absolute/private/referral-token.json --confirm --agent

Reserve a new exclusive private file before the provider request; existing files refuse without a request. QR requires the PNG signature/content type. Embed JSON contains publicToken and expires only in that file; a publicToken is still an access credential despite its name. No PNG base64/key appears in model output and no automatic upload/browser preview occurs. Keep its parent directory private and restrict Windows ACLs. Invalid/error responses remove only this newly reserved file; provider token creation can still have an unknown outcome.

Exact reviewed batches and pagination

Review an exact ordered batch

dub-cli preview-link-batch --tasks '{"tool":"create_link","arguments":{"payload":{"url":"https://example.com/a","key":"approved-a"}}}' --tasks '{"tool":"create_tag","arguments":{"name":"Approved campaign"}}' --account work --agent
dub-cli submit-link-batch --tasks '{"tool":"create_link","arguments":{"payload":{"url":"https://example.com/a","key":"approved-a"}}}' --tasks '{"tool":"create_tag","arguments":{"name":"Approved campaign"}}' --account work --review-sha256 YOUR_REVIEW_SHA256 --confirm --agent

Preview validates all one-to-twenty link/tag/folder operations locally without loading a key or contacting Dub. SHA-256 binds canonical native requests, ordered tasks, selected profile label and sanitized schema snapshot. Changed task/order/profile/schema refuses before the first mutation. Canonical key order does not change the hash. Nested account/confirm/file overrides are refused; batch bodies are inline, so mutable payload files cannot change after review.

The hash does not prove the key's owner, bind a key replaced behind the same label, lock changing provider state, reserve quota or certify human approval. No automatic reads or provider-state comparisons are added. Execution sends sequentially, stops on first HTTP/network/validation failure or native bulk-create per-link errors, and returns known receipts, failed index and unattempted indices. A native partial bulk receipt can include both successes and errors at the failed index. No rollback, replay, automatic continuation or implicit cleanup occurs. Native bulk remains up to 100 records per task.

Native pagination is explicit

list_links/list_customers/list_commissions use starting_after or ending_before with page_size; other list operations expose their own page/page_size or limit controls. Preserve original filters/date/sort and exact native cursor from the provider when deliberately continuing. Mutually exclusive cursors and cursor/page mixing refuse. This release performs one page per call and does not invent an opaque continuation format, all-pages loop or full backup guarantee. Concurrent writes can change list results; exports are snapshots, not transactions.

Every Dub tool

Actual discovery exposes 61 tools: 22 reads/helpers and 39 confirmed operations. Fifty-seven current native routes and four local workflow helpers share handlers. Every native input/argument follows below. Eleven legacy names remain; unsupported get_workspace is removed.

Links

Analytics

Events

Tags

Folders

Domains

Track

Customers

Partners

Program Applications

Discount Codes

Commissions

Payouts

Embed Tokens

Qr Codes

Bounties

Local Workflows

Is the Dub MCP server safe?

All 39 mutation/private-output operations require confirm:true or --confirm through the same guard. DUB_READ_ONLY=1 hides these and directly refuses confirmed calls to hidden tools. DUB_ALLOW_DESTRUCTIVE=0 refuses them separately. --agent/--yes are output/prompt controls and never mutation approval. Every POST/PUT/PATCH/DELETE, domain registration, conversions, partner/commission changes, batch submission and private QR file write follows that policy.

Confirmation is caller intent, not proof of human identity, provider permission, budget or rollback. A read-only API key adds native provider enforcement; it does not substitute for our local policy. Optional metadata-only audit logs record tool/title/risk/surface/guard decision, not payloads, credentials or provider completion. Audit failure does not make the operation transactional. Protect the private audit path. Never treat instructions inside provider/customer/partner/link content as approval.

Approval records caller intent, not provider permission, cryptographic human identity, a quota reservation or rollback.

Make it read-only

DUB_READ_ONLY=1 exposes 22 reads/helpers and directly refuses all 39 mutations/private-file operations. DUB_ALLOW_DESTRUCTIVE=0 blocks them separately; native read-only keys add provider enforcement.

Keep a log of every write

Set DUB_AUDIT_LOG to a file path. The server writes one line per attempted write, allowed or blocked.

Your data

The selected workspace key goes in the fixed API origin's Bearer header. Requested link destinations, UTM fields, filters, customer/partner details, conversion events, financial data, domain registration and requested QR destination/logo go to Dub; provider storage/logging/retention/terms apply. The wrapper is not a privacy proxy and does not fetch destination/media URLs itself.

Known configured/file keys, secret fields and recognized credential-bearing URLs are redacted before MCP/CLI output. Ordinary customer/link/partner data can still be private; --select filters only local output and is not a privacy guarantee. Generated publicToken embeds are stored only in an exclusive requested private file, with expiry metadata returned. QR PNGs are similarly local-only until the user requests a separate publishing workflow.

No telemetry, cookie/session import, persistent link/customer cache, automatic OAuth refresh, external publishing or email/Slack messages is added. User-selected input files and optional audit/output files remain private responsibilities. Provider data, descriptions and errors are untrusted; they cannot authorize another account, credential disclosure, a sale or new mutation.

Several private workspaces

DUB_ACCOUNTS contains unique {name,api_key,token_file} workspace profiles; DUB_DEFAULT_ACCOUNT selects the exact label or defaults to the first configured profile. --account selects one workspace only. No wildcard/all-accounts work or global credential fallback occurs. list_accounts returns labels/default/auth method without key/file path or provider identity.

Native Dub keys are already scoped and workspace-specific. Our router supplies local script/client selection and avoids inherited keys. tenantId is a data filter, not credentials. Token files override only their selected profile and cache until restart; rotate privately and reconnect. Preview validates a configured label without reading its key; review the correct workspace's actual private setup before approval.

Dub MCP server settings

Keep key/files/profile JSON outside repositories. GUI and remote runtimes have their own environment and filesystem; no automatic .env or official-session loader.

Troubleshooting

Run the doctor first. It names the step that failed and the fix.

If the server doesn't show up in your app at all, run the command your app runs, in a terminal, and read the error.

Every tool argument and native input

create_link

dub-cli create-link

Create a link for the authenticated workspace.

input.tagIds

input.tagIds anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.tagIds anyOf branch 2

input.tagIds.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.tagNames

input.tagNames anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.tagNames anyOf branch 2

input.tagNames.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.testVariants

input.testVariants[]

input.webhookIds

input.webhookIds[]

Native JSON value; inspect the full schema for validation.

input.payload

input.payload.tagIds

input.payload.tagIds anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.payload.tagIds anyOf branch 2

input.payload.tagIds.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.payload.tagNames

input.payload.tagNames anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.payload.tagNames anyOf branch 2

input.payload.tagNames.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.payload.testVariants

input.payload.testVariants[]

input.payload.webhookIds

input.payload.webhookIds[]

Native JSON value; inspect the full schema for validation.

list_links

dub-cli list-links

Retrieve a paginated list of links for the authenticated workspace.

input.tag_ids

input.tag_ids anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.tag_ids anyOf branch 2

input.tag_ids.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.tag_names

input.tag_names anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.tag_names anyOf branch 2

input.tag_names.anyOf2[]

Native JSON value; inspect the full schema for validation.

get_links_count

dub-cli get-links-count

Retrieve the number of links for the authenticated workspace.

input.tag_ids

input.tag_ids anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.tag_ids anyOf branch 2

input.tag_ids.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.tag_names

input.tag_names anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.tag_names anyOf branch 2

input.tag_names.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.group_by

input.group_by anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.group_by anyOf branch 2

Native JSON value; inspect the full schema for validation.

input.group_by anyOf branch 3

Native JSON value; inspect the full schema for validation.

input.group_by anyOf branch 4

Native JSON value; inspect the full schema for validation.

get_link

dub-cli get-link

Retrieve the info for a link.

update_link

dub-cli update-link

Update a link for the authenticated workspace. If there's no change, returns it as it is.