Skip to main content
Glama
thenavidm

Dub MCP Server

by thenavidm
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Upsert a link

upsert_link
Destructive

Create or update a short link in the authenticated workspace by destination URL: if the URL exists, return or update it; otherwise, create a new short link.

Instructions

Upsert a link for the authenticated workspace by its URL. If a link with the same URL already exists, return it (or update it if there are any changes). Otherwise, a new link will be created.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
geoNoGeo targeting information for the short link in JSON format `{[COUNTRY]: https://example.com }`. See https://d.to/geo for more information.
iosNoThe iOS destination URL for the short link for iOS device targeting.
keyNoThe short link slug. If not provided, a random 7-character slug will be generated.
refNoThe referral tag of the short link. If set, this will populate or override the `ref` query parameter in the destination URL.
urlNoThe destination URL of the short link.
imageNoThe custom link preview image (og:image). Will be used for Custom Link Previews if `proxy` is true. Learn more: https://d.to/og
proxyNoWhether the short link uses Custom Link Previews feature. Defaults to `false` if not provided.
tagIdNoDeprecated: Use `tagIds` instead. The unique ID of the tag assigned to the short link.
titleNoThe custom link preview title (og:title). Will be used for Custom Link Previews if `proxy` is true. Learn more: https://d.to/og
videoNoThe custom link preview video (og:video). Will be used for Custom Link Previews if `proxy` is true. Learn more: https://d.to/og
domainNoThe domain of the short link (without protocol). If not provided, the primary domain for the workspace will be used (or `dub.sh` if the workspace has no domains).
prefixNoThe prefix of the short link slug for randomly-generated keys (e.g. if prefix is `/c/`, generated keys will be in the `/c/:key` format). Will be ignored if `key` is provided.
tagIdsNoThe unique IDs of the tags assigned to the short link.
accountNoExact configured private workspace profile label; not a tenant or provider account ID.
androidNoThe Android destination URL for the short link for Android device targeting.
confirmNoMust be true for the requested mutation or exclusive private output file.
doIndexNoAllow search engines to index your short link. Defaults to `false` if not provided. Learn more: https://d.to/noindex
payloadNoComplete native JSON body; do not mix with body flags or payload_file. Arrays use repeated JSON object flags or a whole native array in a private file.
rewriteNoWhether the short link uses link cloaking. Defaults to `false` if not provided.
archivedNoWhether the short link is archived. Defaults to `false` if not provided.
commentsNoThe comments for the short link.
folderIdNoThe unique ID existing folder to assign the short link to.
passwordNoThe password required to access the destination URL of the short link.
tagNamesNoThe unique name of the tags assigned to the short link (case insensitive).
tenantIdNoThe ID of the tenant that created the link inside your system. If set, it can be used to fetch all links for a tenant. Pass `null` or an empty string to remove it.
utm_termNoThe UTM term of the short link. If set, this will populate or override the UTM term in the destination URL.
expiresAtNoThe date and time when the short link will expire at.
keyLengthNoThe length of the short link slug. Defaults to 7 if not provided. When used with `prefix`, the total length of the key will be `prefix.length + keyLength`.
partnerIdNoThe ID of the partner the short link is associated with.
programIdNoThe ID of the program the short link is associated with.
expiredUrlNoThe URL to redirect to when the short link has expired.
externalIdNoThe ID of the link in your database. If set, it can be used to identify the link in future API requests (must be prefixed with 'ext_' when passed as a query parameter). This key is unique across your workspace. Pass `null` or an empty string to remove it.
utm_mediumNoThe UTM medium of the short link. If set, this will populate or override the UTM medium in the destination URL.
utm_sourceNoThe UTM source of the short link. If set, this will populate or override the UTM source in the destination URL.
webhookIdsNoDeprecated: You can now enable link.clicked webhooks for all links in a workspace or folder without passing this field manually. An array of webhook IDs to trigger when the link is clicked. These webhooks will receive click event data.
descriptionNoThe custom link preview description (og:description). Will be used for Custom Link Previews if `proxy` is true. Learn more: https://d.to/og
publicStatsNoDeprecated: Use `dashboard` instead. Whether the short link's stats are publicly accessible. Defaults to `false` if not provided.
utm_contentNoThe UTM content of the short link. If set, this will populate or override the UTM content in the destination URL.
payload_fileNoAbsolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags.
testVariantsNoAn array of A/B test URLs and the percentage of traffic to send to each URL.
utm_campaignNoThe UTM campaign of the short link. If set, this will populate or override the UTM campaign in the destination URL.
testStartedAtNoThe date and time when the tests started.
testCompletedAtNoThe date and time when the tests were or will be completed.
trackConversionNoWhether to track conversions for the short link. Defaults to `false` if not provided.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv2.0.0

TDQS

B3.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false, destructiveHint=true, openWorldHint=true and idempotentHint=false, so the safety profile is carried for free. The description adds real behavioral context — matching by URL, returning an existing link, or creating a new one — but omits the destructive nuances (which fields an update overwrites) and the confirm=true requirement for the mutation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short, front-loaded sentences that each carry content with no filler. For a 44-parameter destructive tool it is arguably terse, but every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The core create-or-update contract is covered and the annotations plus 100% schema coverage carry the rest. However, for a high-complexity mutation tool the description leaves the confirm requirement and the destructive/overwrite consequences unstated, so it is adequate but has clear gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all 44 parameters; the baseline is 3. The description clarifies only that URL is the upsert matching key (the schema just calls it the 'destination URL'), which is a marginal addition rather than compensation for any gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Upsert a link') scoped to the authenticated workspace and keyed by URL. The upsert semantics implicitly separate it from create_link/update_link, but it never names those siblings, so differentiation is left to inference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains what happens when the URL exists vs does not, but gives no explicit when-to-use guidance, no prerequisites, and no routing away from create_link or update_link. There is no 'use this when...' or 'prefer X instead' clause.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools