MCP server

There are two MCP servers you will meet around UTMKit, and they do different jobs. https://docs.utmkit.co/mcp belongs to this documentation site: it searches and reads these pages, and nothing else — point an assistant at it to ask how the product works. https://app.utmkit.co/mcp belongs to the product: it operates your workspace — lists, creates, edits and withdraws links, manages campaigns and rules, reads the report — and it needs you to sign in or a token. Same protocol, same path, two hosts. This page is about the second one.

What it is

An MCP (Model Context Protocol) server, spoken over the protocol’s Streamable HTTP transport, inside the product itself. Every tool calls the same operation the console and the API call, so the workspace’s rules apply unchanged: a link the convention would refuse in the console is refused here, with the same sentence, as a tool result your assistant can read and relay or repair. There are two ways in, and they reach the same tools under the same rules:

Sign in (OAuth). claude.ai, Claude Desktop’s connectors, the Claude mobile app and Claude Code connect by sending you to a UTMKit page where you choose the workspace and tick the permissions. No token to copy. The connection then appears under Connected applications on the Tokens page, where you or a workspace admin can disconnect it.
A token. Mint one on the console’s Tokens page with the permissions the assistant should have, as described in Authentication & tokens, and send it on every request:
Authorization: Bearer utmk_…

Either way, the workspace is fixed when you connect; no tool takes a workspace, organization or user argument, and nothing an assistant says can move a call to another one.

Connecting a client

claude.ai and Claude Desktop
Claude Code
Cursor
Claude Desktop (with a token)

In Claude, open Customize → Connectors, choose Add → Add custom connector, name it UTMKit and paste https://app.utmkit.co/mcp as the URL.
Press Connect. A UTMKit page opens; sign in if you are not already.
The page shows that the request comes from Claude (marked Verified), the workspace it will act in, and the permissions it asks for. Pick the workspace, untick anything it should not do, and press Allow.

The connection works on claude.ai, Claude Desktop and the Claude mobile app alike. It stays connected while it is used at least once every 30 days; disconnect it at any time from the Tokens page. On a Team or Enterprise plan, an owner adds the connector for the organization and each member connects with their own UTMKit account.

One command, run in any terminal:

claude mcp add --transport http utmkit https://app.utmkit.co/mcp \
  --header "Authorization: Bearer utmk_…"

Then /mcp in a session lists the server and the tools your token permits. To keep the token out of the command line, put it in an environment variable and reference it from .mcp.json as "Authorization": "Bearer ${UTMKIT_TOKEN}".

In ~/.cursor/mcp.json (every project) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "utmkit": {
      "url": "https://app.utmkit.co/mcp",
      "headers": {
        "Authorization": "Bearer ${env:UTMKIT_TOKEN}"
      }
    }
  }
}

Set UTMKIT_TOKEN in your environment; Cursor resolves it when it connects.

The connector above is the simple way. If you would rather give Claude Desktop a token — to fix its permissions from the Tokens page, say — connect through the mcp-remote bridge in claude_desktop_config.json:

{
  "mcpServers": {
    "utmkit": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://app.utmkit.co/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer utmk_…"
      }
    }
  }
}

The header is split between args and env on purpose: Claude Desktop mangles spaces inside an argument, and the environment variable keeps the space after Bearer intact. Restart Claude Desktop after saving.

Any other MCP client that speaks Streamable HTTP works the same way: by sending a header, or by following the MCP authorization specification to sign in.

The tools

Thirty-one tools, each behind exactly one permission. Every tool also tells your client what kind of action it is — a title, and whether it only reads or whether it changes or removes something — which is what lets an assistant ask before acting. Reads need only the permission; writes also need your role in the workspace to allow them, checked live on every call. Every tool under rules:write also needs an admin or owner role.

Tool	Permission	What it does
`list_links`	`links:read`	The workspace’s links, newest first, with the same search string the console’s box takes
`get_link`	`links:read`	One link by id: destination, UTMs, state, short URL, QR URL
`create_link`	`links:write`	A governed short link, with or without UTMs, or a WhatsApp chat link from a phone number and a message; returns the short URL and the QR URL, plus a warning when the convention is in warn mode
`update_link`	`links:write`	Change destination (or repoint it to a WhatsApp chat), UTMs, campaign, expiry, tags or note; send only what changes
`withdraw_link`	`links:write`	Take a link down; it stops resolving at the edge
`list_tags`	`links:read`	The workspace’s tags with how many links carry each
`create_tag`	`links:write`	Reserve a tag name, optionally with a colour, before any link uses it
`list_campaigns`	`campaigns:read`	Campaigns with their link counts
`get_campaign`	`campaigns:read`	One campaign by id
`create_campaign`	`campaigns:write`	A campaign; a name that already exists returns the existing one
`get_report`	`analytics:read`	The click report, scans reported apart, with the console’s filters and grouping
`get_convention`	`rules:read`	Casing, separator, required parameters and mode
`list_approved_values`	`rules:read`	The approved values per parameter; an empty list means the parameter is open
`list_dependency_rules`	`rules:read`	The “when source is X, medium may be…” rules
`set_convention`	`rules:write`	Change the convention, partially
`approve_values`	`rules:write`	Approve values for one parameter; repeats are no-ops
`retire_value`	`rules:write`	Retire one approved value; retiring a parameter’s last value opens it
`add_dependency_rule`	`rules:write`	Allow values for a target parameter under a driving pair
`remove_dependency_rule`	`rules:write`	Remove one dependency rule
`get_qr_code`	`links:read`	A link’s QR code in the workspace’s design, shown as an image, with PNG and SVG download links that work for an hour
`update_campaign`	`campaigns:write`	Rename a campaign or change its description; links keep their `utm_campaign`
`update_tag`	`links:write`	Rename or recolour a tag; every link keeps it
`delete_tag`	`links:write`	Delete a tag; it comes off every link, the links are untouched
`tag_links`	`links:write`	Add a tag to up to 500 links at once, or take it off them
`assign_campaign`	`links:write`	Move up to 500 links into a campaign, or out of any
`get_workspace`	`links:read`	The workspace, its plan, the period’s usage, the domains a link can use, your role and the token’s permissions
`list_broken_links`	`links:read`	Links whose destination page stopped answering, newest failure first
`create_report_link`	`reports:write`	A link to the workspace’s live report, to send to a client; anyone holding it can read it. Admin or owner only
`delete_campaign`	`campaigns:write`	Delete a campaign; its links keep working and keep their `utm_campaign`, and only lose the container
`list_report_links`	`reports:write`	The workspace’s client report links, live first, with their domain and dates — never their URLs. Admin or owner only
`revoke_report_link`	`reports:write`	Revoke a client report link; whoever holds it sees nothing from the next request. Admin or owner only

A tool the token lacks is hidden, and refused by name if called anyway. The tool list a client receives is filtered to what the token’s permissions and your role allow, and it is recomputed on every list request. A hidden tool is still there: an assistant that calls create_campaign with a links-only token gets a tool result that says This token does not carry campaigns:write. rather than “unknown tool”, so it can tell you exactly which box to tick on the next token. There is no conversions tool. A conversion is a result your server reports against a link — a sale, a sign-up — and a server does that through the API with the conversions:write permission, not through an assistant. See Conversions.

What to expect

A new or edited link is pending for a few seconds, while it reaches the edge; get_link then shows it live. A link deleted with withdraw_link is gone; a link UTMKit blocked for abuse reads blocked (the state:blocked filter of list_links finds those).
With more than one link domain, say which one. A workspace with its own branded domains asks for domain on create_link rather than picking a brand for you.
Every write is attributed to you and to the token or connection, and appears in the activity log like a change made in the console.
Refusals are tool results, flagged as errors, one sentence each: the convention’s refusal, an unapproved value, a destination the scanner rejected, an allowance used up. A protocol error, by contrast, means the client spoke wrongly.
The door is the API’s door. A revoked or expired token, or a disconnected application, fails the connection with 401; an organization with no live subscription with 402; the per-token rate limit applies, with Retry-After. No session outlives its token.
Demotion takes effect on the next call. If your role changes, the write tools disappear from the list on the next tool listing, and a call made before that is refused for the role.

The other server, once more

If your assistant answers a request to create a link with a search result, it is talking to docs.utmkit.co/mcp, the documentation’s server. Reconnect it to app.utmkit.co/mcp, by signing in or with a token.

Overview

Links

Tags

Campaigns

Client reports

Rules

Analytics

Conversions

What it is

Connecting a client

The tools

What to expect

The other server, once more

​What it is

​Connecting a client

​The tools

​What to expect

​The other server, once more

What it is

Connecting a client

The tools

What to expect

The other server, once more