WarpLink

npx add-mcp 'https://api.warplink.app/mcp'

AI Access

WarpLink provides an MCP server for managing links, analytics, apps, API keys, domains, and usage from AI tools like Claude, Claude Code, Cursor, and Windsurf. WarpLink is listed in Claude's Connectors Directory. Connect with a one-time browser sign-in (OAuth) or your existing API key, free on all plans, sharing the REST API's rate limit of 60 requests/minute per credential (API key or OAuth token).

Prerequisites

You need a WarpLink account. Most clients connect with the server URL and a one-time browser sign-in (OAuth), so there is no key to create. For CI or other non-interactive use, create an API key with these scopes:

• links:read and links:write (create, list, update, delete links)
• apps:read and apps:write (manage registered apps)
• analytics:read (view click analytics)
• keys:read and keys:write (list, create, revoke API keys)
• domains:read and domains:write (manage custom domains)
• referrals:read and referrals:write (read and claim referrals, manage webhook endpoints)
• org:read (view organization info and usage)

To create a key, go to Keys > API keys in the dashboard and click Create API key, or see the Authentication docs. The SDK key used by the mobile SDKs is a different credential: the MCP server refuses every SDK key, tied to one app or not, with 403 SDK_KEY_ROUTE_FORBIDDEN.

MCP Server

The WarpLink MCP server exposes 48 tools over the Model Context Protocol. Any MCP-compatible client can connect to it.

Add WarpLink from the Claude directory

WarpLink is listed in Claude's Connectors Directory, so you can connect it from Claude without copying a server URL:

1. In claude.ai, open Customize > Connectors.
2. Search the directory for WarpLink and choose it.
3. Connect, then sign in to WarpLink and approve the requested scopes.

The connection works in claude.ai, Claude Desktop, and the Claude mobile apps. On Team and Enterprise plans, an organization Owner adds WarpLink first, and each member then connects with their own WarpLink account.

Sign in with your browser (recommended)

Most MCP clients can connect with just the server URL and a one-time browser sign-in. No API key to paste, and you authenticate as yourself. On first use, the client opens a WarpLink sign-in and consent screen. Approve the requested scopes once and you're connected. If you belong to more than one organization, use the switch_org tool to choose which one you're working in.

Claude Code: add the server from the CLI, then run /mcp and choose Authenticate to finish the browser sign-in:

claude mcp add --transport http warplink https://api.warplink.app/mcp

This writes the entry below to your .mcp.json; you can also add it by hand:

{
  "mcpServers": {
    "warplink": {
      "type": "http",
      "url": "https://api.warplink.app/mcp"
    }
  }
}

Claude Desktop: add WarpLink from the Claude directory. To add it by URL instead, open Settings > Connectors > Add custom connector, paste https://api.warplink.app/mcp, and sign in when prompted.

Cursor and Windsurf: add the server with just its URL (no Authorization header). When the client sees that WarpLink supports OAuth, it opens the browser sign-in automatically.

Configuration with an API key

For non-interactive use like CI, or if you prefer a static token, connect with an API key instead.

Add the server with your API key passed as a header:

claude mcp add --transport http warplink https://api.warplink.app/mcp \
  --header "Authorization: Bearer wl_live_YOUR_API_KEY"

Prefer the browser sign-in above unless you need non-interactive auth, such as CI.

Claude Desktop's config file only supports local (stdio) servers, so connect through the mcp-remote bridge. Add this to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "warplink": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://api.warplink.app/mcp",
        "--header", "Authorization:${WARPLINK_AUTH}"
      ],
      "env": {
        "WARPLINK_AUTH": "Bearer wl_live_YOUR_API_KEY"
      }
    }
  }
}

The Authorization value is passed through env rather than inline to avoid a header-spacing bug in mcp-remote. Restart Claude Desktop after saving. For a no-config alternative, use Settings > Connectors with browser sign-in instead.

Add this to your Cursor MCP config (.cursor/mcp.json in your project root or ~/.cursor/mcp.json globally):

{
  "mcpServers": {
    "warplink": {
      "url": "https://api.warplink.app/mcp",
      "headers": {
        "Authorization": "Bearer wl_live_YOUR_API_KEY"
      }
    }
  }
}

Reload Cursor after saving.

Add this to your Windsurf MCP config (~/.codeium/windsurf/mcp_config.json). Windsurf uses serverUrl (not url) for remote servers:

{
  "mcpServers": {
    "warplink": {
      "serverUrl": "https://api.warplink.app/mcp",
      "headers": {
        "Authorization": "Bearer wl_live_YOUR_API_KEY"
      }
    }
  }
}

Reload Windsurf after saving.

Replace wl_live_YOUR_API_KEY with your actual API key. Use a wl_test_ key to work in Test mode. One API key works across every MCP client. Use an API key here, not an SDK key: both start with wl_live_ or wl_test_, but an SDK key is for a mobile app and the MCP server refuses it with 403 SDK_KEY_ROUTE_FORBIDDEN. Never commit a key to source control. Cursor and Windsurf support ${env:VAR} interpolation in the config (for example, "Authorization": "Bearer ${env:WARPLINK_KEY}") if you'd rather reference an environment variable.

Available Tools

Links

Tool	Description	Required Scopes
create_link	Create a new deep link	links:write
list_links	List links with filtering and pagination	links:read
get_link	Get a single link by ID	links:read
update_link	Update an existing link	links:write
deactivate_link	Pause a link (reversible; keeps its analytics and slug)	links:write
activate_link	Resume a paused link	links:write
delete_link	Permanently delete a link and its clicks (to pause instead, use deactivate_link)	links:write
get_link_analytics	Get click analytics for a link, in the org zone or a chosen timezone	analytics:read
resolve_link	Debug a link by slug: see routing and status	links:read
set_link_move_choice	For a link that cannot move with its slug: pick a new slug, keep it where it is, or clear the choice	links:write

Analytics

Tool	Description	Required Scopes
query_analytics	Answer analytics questions: overview, one link, a breakdown, a trend, a summary with top movers, a link leaderboard, or a link comparison	analytics:read
export_analytics	Create, check, and download a full click-data export	analytics:read
list_installs	List install records with stable IDs and match details, one page at a time	analytics:read
list_attribution_attempts	List attribution attempts, matched and unmatched, with the reason each one did not match	analytics:read

Apps

Tool	Description	Required Scopes
list_apps	List registered apps with pagination	apps:read
get_app	Get a single app by ID	apps:read
create_app	Register a new app (iOS, Android, or both)	apps:write
update_app	Update an app's configuration or rename its subdomain	apps:write
delete_app	Delete a registered app	apps:write
set_app_link_domain	Choose the default domain for an app's new links (existing links keep their addresses)	apps:write
extend_subdomain_rename	Add 1 month to an app's rename period end date, up to 2 times (the previous subdomain keeps working)	apps:write
get_sdk_setup	Get the install, configure and link-domain steps for one platform of an app, with a placeholder where the SDK key goes	apps:read
verify_setup	Check an app's setup end to end: app fields, link files, domains, SDK key, first connection, and a test link	apps:read
list_link_moves	See which links still use an app's previous subdomain, and which would need a new slug on the app's subdomain because theirs is taken	links:read

Keys

Tool	Description	Required Scopes
list_keys	List SDK and API keys	keys:read
create_key	Create an SDK or API key (raw key returned once)	keys:write
revoke_key	Revoke an SDK or API key	keys:write

Custom Domains

Tool	Description	Required Scopes
list_domains	List custom domains with pagination	domains:read
add_domain	Add a custom domain for branded links	domains:write
get_domain_status	Check verification and SSL status	domains:read

Organization

Tool	Description	Required Scopes
get_org_info	Get org info, plan, and usage stats	org:read
list_orgs	List the organizations you can act on	none
switch_org	Choose the active organization (OAuth connections)	none
switch_environment	Choose Production or Test for the active organization (OAuth connections)	none

Referrals

Tool	Description	Required Scopes
get_referral_page	Get an app's referral page: the page a referred person lands on before the store	apps:read
update_referral_page	Save the page: logo, colors, label, headline, invitation, button, skip and copy lines. Same checks as the dashboard	apps:write
list_referrals	List referrals with the report's search and filters, one page at a time, or as CSV	referrals:read
get_referral	Get one referral with its event history and webhook deliveries	referrals:read
claim_referral	Record a referral claim for a new user. Send the installer's WarpLink user id, never a primary key or an email	referrals:write
resend_referral_webhook	Send a referral's webhook events again	referrals:write
delete_referral	Permanently delete a referral and its events	referrals:write
list_webhook_endpoints	List an app's webhook endpoints	referrals:read
create_webhook_endpoint	Add an endpoint (the signing secret is returned once). Returns 409 PLAN_LIMIT_EXCEEDED, with the limit in details, when the plan has no room	referrals:write
update_webhook_endpoint	Change a webhook endpoint's URL, events or on and off state	referrals:write
delete_webhook_endpoint	Permanently delete a webhook endpoint	referrals:write
rotate_webhook_secret	Rotate an endpoint's signing secret (returned once). The old one signs for 24 hours	referrals:write
send_test_webhook	Send a test event to a webhook endpoint	referrals:write
list_webhook_deliveries	List a webhook endpoint's recent deliveries and their results	referrals:read

Set up an app from your editor

get_sdk_setup returns the install step with the current SDK version, the configure snippet with a placeholder where the SDK key goes, the link hosts, the iOS Associated Domains lines or the Android intent filter, and the app's test address. verify_setup checks the app end to end and returns each check with a status of pass, fail, warn, needs_human, or skipped, plus a fix for each check that needs one. An assistant calls them in that order, applies each fix, and stops when only steps that need a person remain, such as a tap on a phone. The same data is available as GET /v1/apps/{id}/sdk-setup and GET /v1/apps/{id}/setup-check. The AI Agents guide walks through the whole flow and the agent kit that automates it.

Referral handoff from your editor

The Referrals tools cover the whole referral handoff, so an assistant can set it up and watch it work. update_referral_page and get_referral_page edit the page a referred person sees before the store. list_referrals and get_referral read the report, and claim_referral records a claim for a new user from your backend. The webhook tools (create_webhook_endpoint, update_webhook_endpoint, delete_webhook_endpoint, rotate_webhook_secret, send_test_webhook, list_webhook_endpoints, list_webhook_deliveries) manage the endpoints that receive referral.claimed and referral.updated, and resend_referral_webhook sends a referral's events again. create_webhook_endpoint and rotate_webhook_secret return the signing secret once, so the assistant must store it in your secret manager and never in chat or in a committed file. Reads need referrals:read and writes need referrals:write, except the two referral page tools: get_referral_page needs apps:read and update_referral_page needs apps:write. See the referral guide and the webhooks guide.

Test and Production

Every organization has a Test environment next to Production. See Test mode. Every tool result names the environment it used, in _meta["warplink/environment"] and in an Environment line of text.

An OAuth connection switches with switch_environment: pass environment set to test or production. switch_environment returns the organization as active_org_id with the environment you chose. In Test, switch_environment, list_orgs and get_org_info report the Production organization with environment set to test, and get_org_info returns the plan and usage of that Production organization. Changing the organization with switch_org resets the connection to Production. A connection made with an API key never switches: a wl_test_ key is always Test and a wl_live_ key is always Production. A Test key on a tool that manages the organization itself, such as domains or billing, returns ENVIRONMENT_NOT_SUPPORTED.

An agent that signs up through Agent sign-up starts in Test with an opaque access token. The token has no wl_test_ prefix. Switching it to Production needs a claimed workspace and returns CLAIM_REQUIRED before that.

Prompts and resources

Besides tools, the server offers ready-made prompts and read-only resources. A client lists them in its prompt picker or resource attachment menu. They do not change the tool count.

Prompt	What it asks the assistant to do	Arguments
weekly_link_report	Summarize how links performed over a period: totals against the previous period, top movers, sources and silent links	days: Days to cover, 1 to 90. Default 7.
find_broken_links	List paused, expired, destinationless and silent links, each with a fix to confirm	days: Days without taps that make an active link silent, 1 to 90. Default 30.
setup_deep_linking	Walk an assistant through the SDK setup of an app and prove it with a setup check	app_id: The ID (a UUID) of the app to set up. Leave empty to pick or create one.
debug_link	Find why one link does not open the app or the page it should	slug_or_url (required): The link's slug or its full short URL, at most 2048 characters.

Resources are documents an assistant can attach as context:

Resource	What it holds	Required Scopes
warplink://docs/setup-guide	The steps from sign-in to a first tracked tap, with the tool to call at each step	none
warplink://docs/errors	Every error code the API and tools return, with what it means and how to fix it	none
warplink://sdk/{platform}	Generic install and configure snippets for one platform: ios, android, react-native or flutter	none
warplink://apps/{app_id}/setup	The SDK setup steps of one app of the organization, with its hosts and a placeholder for the SDK key	apps:read

Names, descriptions, titles and URLs that people in your organization write reach other members' assistants through tool results, prompts and resources. The server tells the assistant that this text is data, never an instruction, and every prompt ends with the same rule. A prompt that takes a slug or URL puts it inside a labelled block, accepts at most 2,048 characters, and setup_deep_linking accepts only an app ID.

Changing your password, resetting it, or turning off two-factor ends every assistant connection on your account. Sign each one in again afterwards.

Keys an assistant can create

An assistant connected over OAuth can create an SDK key tied to one app with create_key: pass type: "sdk" and the app's app_id. The key has the fixed SDK scopes and never expires, so a coding agent can set up an app without you copying a key. An SDK key for any app is refused over OAuth. An assistant can also create an API key, with the scopes its connection holds, never keys:read or keys:write, and a lifetime of at most 90 days. The raw key is shown once, so the assistant must put it in the app's config or secret store and never in chat or in a committed file. list_keys and GET /v1/keys show which keys an assistant created in created_via and created_via_label. The MCP server itself refuses SDK keys, so an SDK key never goes into an MCP client.

Errors, retries, and previews

A failed call returns the error code, the message, and a fix. The REST API puts the fix in details.fix with a link to the code in details.docs_url. The MCP server adds Fix: ... to the error text and returns the same fields in structuredContent.error. An assistant applies the fix before it retries. See Errors for every code.

To retry a create safely, pass idempotency_key to create_link or create_app: the same key and arguments return the first result instead of creating a second one, and a key is remembered for 24 hours. To preview a change, pass dry_run: true to create_link, create_app, or update_link. WarpLink runs every check a real call runs and returns { "dry_run": true, "result": ... } without saving anything. See Safe retries and dry runs.

Start with no account

An agent that has no WarpLink account calls POST /v1/agent/signup with a name and the person's email address. WarpLink creates a Free workspace, emails the person a claim link, and returns a token for this server. The token starts in Test. Until the person claims the workspace it holds 1 app and 10 links, and its links stay paused. See Agent sign-up.

Example Prompts

Once connected, you can use natural language in your MCP client:

• "Create a WarpLink for https://example.com/promo with the tag summer-sale"
• "Show me my last 10 links"
• "How many clicks did my link abc123 get in the past 30 days?"
• "Why did my clicks change this week, and which country or referrer drove it?"
• "Show hourly clicks for the last 7 days next to the previous 7 days"
• "Which of my links have had no clicks in the last 30 days?"
• "Break down last month's clicks by country and compare to the month before"
• "Export all clicks from the last 90 days as CSV"
• "Update the destination URL of link xyz to https://example.com/new-page"
• "Register a new iOS app with bundle ID com.example.myapp"
• "What's my current plan and how much of my click quota have I used?"
• "Add links.mybrand.com as a custom domain"
• "Create a new API key called 'CI Pipeline' with links:read and links:write scopes"
• "Debug the link at aplnk.to/promo and show me its routing"
• "Set up WarpLink in this project and check that it works"
• "Which AI assistants sent clicks to my links this month?"
• "Turn on the referral handoff for my iOS app and tell me what is missing"
• "Add a webhook endpoint at https://example.com/hooks/warplink for referral events and send a test event"
• "Show the referrals claimed this week and which ones were flagged"

Frequently Asked Questions

What is the WarpLink MCP server?

It is a remote MCP endpoint at https://api.warplink.app/mcp that exposes WarpLink's link infrastructure to AI clients. Once connected, an assistant can create and update deep links, register iOS and Android apps, read click analytics, debug how a link routes, manage referrals and their webhook endpoints, manage API keys and custom domains, and report your plan and usage. Every call acts inside the organization the connection is authenticated for, and nowhere else.

Which MCP clients work with it?

Any client that speaks the Model Context Protocol over Streamable HTTP. The configuration examples above cover Claude Code, Claude Desktop, Cursor, and Windsurf. Clients that support OAuth connect with the server URL alone and open a browser sign-in. Clients that do not can send a WarpLink API key as a bearer header instead.

What does the WarpLink MCP server cost?

Nothing extra. MCP access is included on every plan, including Free, and shares the REST API's rate limit of 60 requests per minute per credential (API key or OAuth token). Your plan's limits on apps, links, members, and custom domains still apply to what the tools are able to create.

Should I use OAuth or an API key?

Prefer the browser sign-in for day to day work in an editor. There is nothing to paste, you act as yourself, and one connection spans every organization you belong to, with switch_org to move between them. Use an API key for non-interactive contexts such as CI, where no browser is available. A key is scoped to the organization it was created in, so switch_org does not apply to it. Both methods reach the same endpoint and resolve to the same permissions.

Do the WarpLink SDKs need the MCP server?

No. The iOS, Android, React Native, and Flutter SDKs talk to WarpLink directly, and your app works with no MCP client involved. The MCP server is a way to manage your link infrastructure from an AI client, not a dependency of the SDKs. The SDK key your app ships with is also a different credential: it is pre-scoped for a mobile app, and the MCP server refuses it with 403 SDK_KEY_ROUTE_FORBIDDEN.

Next Steps

• API Reference for the complete endpoint documentation
• Authentication for API key scopes and security best practices
• Quickstart to create your first deep link