From 10b6e51e1611f5602988a27ad0a9327be1593f10 Mon Sep 17 00:00:00 2001 From: Darshil Rathod <69842641+RathodDarshil@users.noreply.github.com> Date: Thu, 15 Oct 2026 12:56:28 +0000 Subject: [PATCH 1/4] docs(mcp): set up Linkrunner from Claude with sign-in, no token (LIN-3708) Rewrite /features/mcp around the OAuth sign-in connector: connect per client, set up a new app from a chat, rules for new projects, an updated tool reference, token connections for existing setups and ChatGPT, security and troubleshooting. Move the page into Getting Started, add a contextual menu and agent instructions for llms.txt and Markdown pages, and point the quickstart, introduction and agent skills pages to it. Co-Authored-By: Claude Opus 5.5 --- ai-agent-skills.mdx | 8 + docs.json | 29 ++- features/mcp.mdx | 556 ++++++++++++++++++++++++++++++-------------- introduction.mdx | 5 +- quickstart.mdx | 4 + 5 files changed, 418 insertions(+), 184 deletions(-) diff --git a/ai-agent-skills.mdx b/ai-agent-skills.mdx index 3dd9ff46..63195366 100644 --- a/ai-agent-skills.mdx +++ b/ai-agent-skills.mdx @@ -56,6 +56,14 @@ Cross-cutting skills that are not tied to one platform: The **deep link troubleshooter** diagnoses why Universal Links / App Links open the browser instead of the app. The **events** skill wires up the correct event taxonomy, revenue tracking, and server-side APIs. The **webhooks** skill writes a receiver in your backend that verifies the `linkrunner-key` header and handles install/signup payloads. +## Create the project from a chat + +The skills change your app's code. They do not create your Linkrunner project. +To create the project and get the SDK token without opening the dashboard, add +the [Linkrunner connector](/features/mcp) to Claude or Claude Code and ask it to +set up Linkrunner for your app. Then use the skill to add the SDK with that +token. + ## Options ```bash diff --git a/docs.json b/docs.json index 2c8b7c39..0568f540 100644 --- a/docs.json +++ b/docs.json @@ -8,6 +8,30 @@ "dark": "#3D3BD6" }, "favicon": "/favicon.svg", + "contextual": { + "options": [ + "copy", + "view", + "chatgpt", + "claude", + { + "title": "Connect Linkrunner to Claude Code", + "description": "Add the Linkrunner MCP server and sign in", + "icon": "plug", + "href": "https://docs.linkrunner.io/features/mcp#claude-code" + } + ] + }, + "markdown": { + "instructions": [ + "Linkrunner has a remote MCP server at https://mcp.linkrunner.io/mcp. People sign in to Linkrunner in a browser popup (OAuth), so there is no token to copy. New users sign up in the same popup.", + "Before sign-in, only get_linkrunner_overview and search_documentation work. Any other tool asks the person to sign in first.", + "To set a person up: connect the server, then call get_my_account, list_projects, find_app_in_store (confirm the right app with the person), and create_project. create_project returns the project ID and the SDK token. Install the SDK with that token. get_sdk_configuration returns the token again later.", + "Rules: a company email is needed to create a project (Gmail accounts cannot), an app project needs a live App Store or Play Store listing, a person can create up to 3 projects per day from an AI assistant, and using an existing project needs the Admin, Owner or Manager role.", + "Claude Code: claude mcp add --transport http linkrunner https://mcp.linkrunner.io/mcp, then run /mcp to sign in.", + "Guides: connector setup and tool reference at https://docs.linkrunner.io/features/mcp, manual setup at https://docs.linkrunner.io/quickstart. To integrate the SDK in a codebase, use the @linkrunner/skills package: https://docs.linkrunner.io/ai-agent-skills" + ] + }, "navigation": { "tabs": [ { @@ -15,7 +39,7 @@ "groups": [ { "group": "Getting Started", - "pages": ["introduction", "quickstart", "features/website-projects", "ai-agent-skills"] + "pages": ["introduction", "quickstart", "features/mcp", "features/website-projects", "ai-agent-skills"] }, { "group": "SDK Guides", @@ -209,8 +233,7 @@ { "group": "Developer Tools", "pages": [ - "features/webhooks", - "features/mcp" + "features/webhooks" ] } ] diff --git a/features/mcp.mdx b/features/mcp.mdx index c8930302..5eeb364f 100644 --- a/features/mcp.mdx +++ b/features/mcp.mdx @@ -1,183 +1,198 @@ --- -title: "Connect Linkrunner to AI assistants" -sidebarTitle: "MCP" -description: "Connect Linkrunner to Claude, ChatGPT, Claude Code, or Codex with MCP." -icon: "sparkles" +title: "Set up and use Linkrunner from Claude and other AI assistants" +sidebarTitle: "AI assistants (MCP)" +description: "Connect the Linkrunner MCP server to Claude to set up mobile attribution for your app and ask about your installs and campaigns from a chat." +icon: "plug" --- -## Overview +Add the Linkrunner connector to Claude and you can create your Linkrunner project, get your SDK token, and ask how your campaigns perform, all from a chat. You sign in to Linkrunner in a popup, so there is no token to copy. If you don't have a Linkrunner account yet, you create one in the same popup. -Linkrunner ships a remote Model Context Protocol (MCP) server. Connect it to a -supported AI assistant, then ask questions about your project's data directly -from chat: +The connector address is: -- "How did my campaigns perform last week?" -- "Compare my Meta vs Google performance for the last 7 days." -- "Which campaigns should I cut based on ROAS?" -- "Why did installs drop yesterday?" -- "How much of my growth is organic?" -- "Where do users drop off between install and checkout?" - -With the ad-accounts capability, the assistant can also read from the Meta and -Google accounts you have connected: - -- "How much did we spend on Meta last week, by campaign?" -- "Which Google ad groups are paused right now?" -- "What targeting does our retargeting ad set use?" -- "Compare Meta's reported spend with Linkrunner's installs for yesterday." - -The assistant can also make a defined set of changes for you: - -- "Create a Meta campaign for the Diwali sale pointing at our sneakers page." -- "Pause every campaign with no installs in the last 30 days." -- "Save a funnel for install, sign up, then purchase." +```text +https://mcp.linkrunner.io/mcp +``` Editing tools act on your live project, not a sandbox. The connector can create -and edit campaigns, funnels, domains, store listings, webhooks, and postback -event mappings. A few of these send real traffic to third parties or cannot be -undone. Read [What the connector can change](#what-the-connector-can-change) -before you share the connector with a team. +projects, and create and edit campaigns, funnels, domains, store listings, +webhooks, and postback event mappings. A few of these send real traffic to +third parties or cannot be undone. Read +[What the connector can change](#what-the-connector-can-change) before you +share the connector with a team. -## Prerequisites +## Connect -- A project on Linkrunner that you have access to. -- The **Admin** or **Member** role on that project. **Influencers** cannot mint - MCP tokens. -- A supported client: Claude Code, Claude on Desktop or web, Codex CLI, or - ChatGPT web. -- Editing tools run as the person who created the token, using that person's - project permissions. A role that cannot edit in the dashboard cannot edit - through the connector either. +Add the connector once. Your assistant asks you to sign in the first time it needs your Linkrunner account. -## Setup - -### 1. Generate a token - -1. Open the [Linkrunner dashboard](https://dashboard.linkrunner.io) and switch - to the project you want to connect. -2. Click **MCP** in the sidebar. -3. Choose what the token may do: - - **Read Linkrunner data** is always on. - - **Make changes in Linkrunner** lets the assistant use the editing tools - listed under - [What the connector can change](#what-the-connector-can-change). Turn it - off for a read-only token. - - **Read connected ad accounts** lets the assistant read your connected - Meta and Google accounts. See - [What the connector can read from your ad accounts](#what-the-connector-can-read-from-your-ad-accounts). -4. Click **Generate Token**. -5. The dashboard shows a one-time **Server URL** with the token already - embedded as a query parameter. Copy it now. The full URL will not be shown - again. - -Capabilities are fixed once a token exists. To change them, generate a new -token and revoke the old one. Tokens created before capabilities existed keep -read and change access, and no ad-account access. + + + These steps are the same in Claude on the web, desktop, and mobile. - -The URL contains the token as a query parameter. Treat it like a password: -don't paste it into shared documents, screenshots, or chat threads. Revoke it -from the dashboard if it leaks, and generate a new one. - + 1. Open **Customize → Connectors**. + 2. Select **Add custom connector** and name it `Linkrunner`. + 3. Enter `https://mcp.linkrunner.io/mcp` as the URL. + 4. Under **Authentication**, choose **Sign in when needed**. + 5. Under **OAuth client**, choose **Use Claude's published identity**. -### 2. Connect your client + In a chat, select **+ → Connectors** and enable Linkrunner for that + conversation. -Choose your client in the dashboard to see its setup instructions. The -token is part of the Server URL, so no separate authentication step is needed. + The Claude Free plan allows one custom connector. -![Choose a client for the Linkrunner MCP connection](/images/mcp/connect-linkrunner.png) + On Team or Enterprise, an Owner adds the connector under + **Organization settings → Connectors → Add → Custom**. Members then click + **Connect** next to Linkrunner. + - - Copy the command under **Register the Linkrunner MCP server** and run it in - a terminal: + Run this in a terminal: ```bash - claude mcp add linkrunner --scope user --transport http "" + claude mcp add --transport http linkrunner https://mcp.linkrunner.io/mcp ``` - Start a new Claude Code session and run `/mcp` to verify the connection. + Then run `/mcp` in Claude Code to sign in. You can also skip this and ask + for something that needs your account. Claude Code asks you to sign in at + that point. - - These steps work in Claude Desktop and at [claude.ai](https://claude.ai). + + Any MCP client that supports OAuth sign-in can connect. Add + `https://mcp.linkrunner.io/mcp` as a remote MCP server. The server supports + Client ID Metadata Documents and Dynamic Client Registration. - On Free, Pro, or Max: + For ChatGPT, use [Connect with a token](#connect-with-a-token-existing-setups-and-chatgpt). + + - 1. Open **Customize → Connectors**. - 2. Select **+ → Add custom connector** and name it `Linkrunner`. - 3. Paste the Server URL from the dashboard. +### What happens when you sign in + +You can ask what Linkrunner is, or search the documentation, before you sign in. Any other request needs your account. Claude then shows a **Connect** button in the chat. + +1. Click **Connect**. A window opens at `auth.linkrunner.io`. +2. Sign in, or sign up if you are new, with Google or an email link. +3. Review the consent page. It reads "claude.ai wants to access your Linkrunner account", shows the email you signed in with, and lists what the connector can do: see your projects and reports, and create projects and make changes. +4. Approve. The chat continues with your request. + +Claude keeps you signed in and refreshes the session automatically. To end the session, disconnect or remove the connector. + +## Set up a new app from a chat + +Start with a message such as: + +> Set up Linkrunner attribution for my app Acme Shop + +Your assistant then works through these steps. It asks you to confirm before it creates anything. + + + + The assistant calls `get_my_account` to see which email you signed in with + and whether your account can create projects. It then calls + `list_projects` to show any projects you already have. + + + The assistant calls `find_app_in_store` to search the App Store or Play + Store by name, or to look up a store link you paste. Confirm which listing + is your app. + + + The assistant calls `create_project` with the project name, company, project + type (app or website), store links, report timezone, and optionally the + billing currency (USD or INR). Check these details before you approve. The + tool returns the new project ID and your SDK token. + + + Add the SDK to your app with that token. The assistant can find the guide + for your platform with `search_documentation`. In a code editor, the + [Linkrunner agent skills](/ai-agent-skills) can make the code changes for + you. + + To see the SDK token again later, ask for it. The assistant calls + `get_sdk_configuration`. + + + Follow [Integration testing](/testing/integration-testing) to confirm that + Linkrunner receives installs from your app. + + + +After the project exists, every other tool works with it. If you have more than one project, name the project in your question. + +### Rules for new projects + +These are the same rules the dashboard applies. + +- **You need a company email to create a project.** Gmail accounts can sign up and be invited to existing projects, but cannot create one. For help, contact [support@linkrunner.io](mailto:support@linkrunner.io). +- **An app project needs a live App Store or Play Store listing.** You cannot set up an app that is not published yet. Come back once its listing is live. A website-only project needs the website URL instead. +- **You can create up to 3 projects per day from an AI assistant.** +- **To use an existing project, you must be its Admin, Owner, or Manager.** +- New projects get the same free allowance and billing setup as projects you create in the dashboard. See [Billing](/billing/overview). - On Team or Enterprise, an Owner or Primary Owner first adds the Server URL - under **Organization settings → Connectors**. Members then open - **Customize → Connectors** and connect Linkrunner. +## What you can ask - In a chat, select **+ → Connectors** and enable Linkrunner for that - conversation. +Your assistant picks the right tool for your question. Some examples: - See [Anthropic's custom connector guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) - for current plan and organization details. - +- "What is Linkrunner, and does it work with Flutter?" +- "What is my SDK token for Acme Shop?" +- "How did my campaigns perform last week?" +- "Compare my Meta vs Google performance for the last 7 days." +- "Which campaigns should I cut based on ROAS?" +- "Why did installs drop yesterday?" +- "How much of my growth is organic?" +- "Where do users drop off between install and checkout?" +- "Is my iOS link setup right? The link opens the App Store instead of my app." +- "Is Meta receiving my purchase events?" - - Copy the command under **Register the Linkrunner MCP server** and run it in - a terminal: +The assistant can also make a defined set of changes for you: - ```bash - codex mcp add linkrunner --url "" - ``` +- "Create a Meta campaign for the Diwali sale pointing at our sneakers page." +- "Pause every campaign with no installs in the last 30 days." +- "Save a funnel for install, sign up, then purchase." - Start a new Codex session and run `/mcp` to verify the connection. - +### Built-in prompts - - - Custom MCP apps currently work in ChatGPT on the web. ChatGPT Desktop is - not supported. Pro apps can use read and fetch tools only. Turn off - **Make changes in Linkrunner** before generating a token on Pro. Full MCP - support, including write tools, is rolling out in beta to Business and - Enterprise/Edu workspaces. - +The connector includes three starter prompts. Clients that support MCP prompts +show them in their prompt picker: - 1. Enable Developer mode: - - On Pro, open **Settings → Apps → Advanced settings**. - - On Business, an admin or owner enables Developer mode from - **Workspace settings → Apps → Create**. - - On Enterprise/Edu, an admin grants access under **Permissions & Roles - → Connected Data**. Enabled users then turn on Developer mode under - **Settings → Apps → Advanced settings**. - 2. Open **Settings → Apps → Create**. On Business, an admin or owner uses - **Workspace settings → Apps → Create** instead. - 3. Name the app `Linkrunner` and paste the Server URL as the MCP endpoint. - 4. Choose no authentication, then select **Scan tools** and **Create**. - 5. Test the draft in a new chat. To make it available to workspace members, - an admin or owner opens **Workspace settings → Apps → Drafts** and - selects **Publish**. - 6. Start a chat, select **Apps**, and choose Linkrunner. +- **Daily briefing:** yesterday's performance summary in 1-2 paragraphs. +- **Weekly review:** this week vs last week, with anomalies and a + keep/cut/scale recommendation list. +- **Cut list:** the worst-performing active campaigns, with reasoning. - See [OpenAI's MCP apps guide](https://help.openai.com/en/articles/12584461) - for current plan and role requirements. - - +These are shortcuts. You can always ask the same questions in your own words. - -You only need one connection per client and project. If you manage several -Linkrunner projects, generate a token for each project and add a separate -connection with a clear name. Tokens are scoped to a single project. - +## Tool reference -### 3. Try it +Your assistant reads each tool's description and decides which to call. You +don't need to call tools yourself. Tools that change your project are listed +separately under [What the connector can change](#what-the-connector-can-change). -Open a new chat or CLI session, make sure Linkrunner is enabled, and ask one of -the starter prompts above. The assistant fetches data through the connector -and answers in plain language. +On a sign-in connection, every project tool takes the project ID, and the +assistant gets it from `list_projects` or `create_project`. On a +[token connection](#connect-with-a-token-existing-setups-and-chatgpt), the +token decides the project, and the overview and account tools are not offered. -## What you can ask +### Before you sign in + +| Tool | Use it for | +|------|------------| +| `get_linkrunner_overview` | What Linkrunner is, which SDKs it supports, how setup works through the connector, and what a new project needs. | +| `search_documentation` | Searches docs.linkrunner.io and returns links and the relevant content. | -The connector exposes the following tools. Your assistant picks them -automatically based on your question. +### Account and setup + +| Tool | Use it for | +|------|------------| +| `get_my_account` | The email you signed in with, and whether your account can create projects. | +| `list_projects` | Your existing projects, with their IDs, store links, and timezones. | +| `find_app_in_store` | Search the App Store or Play Store by app name, or look up a store link. | +| `get_sdk_configuration` | The project's SDK token, with links to the dashboard and the SDK docs. | + +`create_project` also belongs to setup. It is listed under [Projects](#projects) because it creates something. + +### Project data | Tool | Use it for | |------|------------| @@ -201,9 +216,6 @@ automatically based on your question. | `list_postback_event_maps` | Event mappings sent to each ad network, and which are network defaults. | | `get_webhook` | Whether a webhook is configured, its host, and its organic setting. | -Your assistant reads these tools' descriptions and decides which to call. You -don't need to invoke them manually. - `list_campaigns`, `get_channel_performance`, and `get_organic_performance` return only the metric groups your assistant asks for (installs, spend, @@ -213,12 +225,22 @@ mistakes "not fetched" for "measured zero". Ask for a metric by name and it will fetch it. +### Setup and delivery checks + +| Tool | Use it for | +|------|------------| +| `check_link_setup` | Checks your iOS and Android link setup: the app details saved in Linkrunner, what your link domains serve at `/.well-known/apple-app-site-association` and `/.well-known/assetlinks.json`, and where a campaign link lands on iOS, Android, and the Facebook in-app browser. | +| `get_postback_delivery_log` | Conversions sent to ad networks and affiliates over the last 7 days by default (up to 30 days): delivered, failed, and not sent, by network and by event, with the network's error messages. | + ## What the connector can read from your ad accounts -Tokens created with **Read connected ad accounts** get six more tools. They -read from the Meta Marketing API and the Google Ads API using the ad accounts -already connected to the project under Settings, and nothing else. They cannot -change anything on Meta or Google. +Ad-account tools are not available on a sign-in connection yet. To use them, +[connect with a token](#connect-with-a-token-existing-setups-and-chatgpt) and +turn on **Read connected ad accounts** when you generate it. + +These tools read from the Meta Marketing API and the Google Ads API using the +ad accounts already connected to the project under Settings, and nothing else. +They cannot change anything on Meta or Google. | Tool | Use it for | |------|------------| @@ -226,7 +248,8 @@ change anything on Meta or Google. | `get_ad_insights` | Spend, impressions, clicks, CTR, CPC, CPM, reach and frequency as the ad network reports them, at account, campaign, ad set or ad group, or ad level, with the network's own conversions under `network_reported`. Optional breakdown by date, device, platform, country, age or gender. | | `list_ad_entities` | Campaigns, ad sets or ad groups, ads, creatives, audiences, conversion actions and keywords, with status, budget and objective. | | `get_ad_entity` | Every readable field of one object, such as an ad set's targeting or a campaign's bidding strategy. | -| `query_ad_network` | Anything the three tools above cannot express, using the network's own field names: video metrics, impression share, quality rankings, placements, hourly and search-term reports, country, age and gender on Google, attribution-window comparisons on Meta, filters on any field, sorting, and object types such as pixels, labels, saved audiences and asset groups. | +| `get_ad_recommendations` | The recommendations Meta shows for one connected Meta ad account, such as creative fatigue or limited budget, plus the account's opportunity score. | +| `query_ad_network` | Anything the tools above cannot express, using the network's own field names: video metrics, impression share, quality rankings, placements, hourly and search-term reports, country, age and gender on Google, attribution-window comparisons on Meta, filters on any field, sorting, and object types such as pixels, labels, saved audiences and asset groups. | | `ad_network_reference` | Searches the field catalogs of both networks. Your assistant uses it to find exact names before a `query_ad_network` call, and to explain what a metric means. | The catalogs behind these tools come from the networks themselves: Google's @@ -299,11 +322,18 @@ assistant picks the right tool. Describe what you want changed, and confirm the summary it gives you before it writes. -Every tool below writes to your live project. Your assistant asks before making -an ambiguous change, but it is worth being specific about what you want, -especially for the tools marked as sending live traffic or being irreversible. +Every tool below writes to your live account or project. Your assistant asks +before making an ambiguous change, but it is worth being specific about what you +want, especially for the tools marked as sending live traffic or being +irreversible. +### Projects + +| Tool | Use it for | +|------|------------| +| `create_project` | Create a new project in your account and get its project ID and SDK token. Sign-in connections only. See [Rules for new projects](#rules-for-new-projects). | + ### Campaigns | Tool | Use it for | @@ -311,6 +341,8 @@ especially for the tools marked as sending live traffic or being irreversible. | `create_campaign` | A new tracking link for an ad creative, an influencer, an organic channel, or a web-to-app flow. | | `edit_campaign` | Rename, pause or resume, change the deep link, swap the store listing, or reassign the ad account. | | `create_deeplink` | A per-ad-set or per-creative deep link under a Meta or Google campaign. | +| `update_custom_channel` | Rename a custom channel label. See the troubleshooting note on [renaming a custom channel](#troubleshooting). | +| `delete_custom_channel` | Remove a custom channel label. The campaign itself is not deleted. | A deep link has to be a full URL on one of your own tracking domains, for example `https://links.yourbrand.com/product/sneakers`. An external URL is @@ -389,19 +421,140 @@ An ad network's built-in defaults also appear in `list_postback_event_maps`. They are always active and cannot be changed or removed. To override one, add your own mapping for the same event. -## Built-in prompts +## Connect with a token (existing setups and ChatGPT) -The connector includes three starter prompts. Clients that support MCP prompts -show them in their prompt picker: +Connections made with a dashboard token keep working. Use a token for ChatGPT, +for Codex CLI, or when you need the ad-account tools. A token connection is +fixed to one project. -- **Daily briefing:** yesterday's performance summary in 1-2 paragraphs. -- **Weekly review:** this week vs last week, with anomalies and a - keep/cut/scale recommendation list. -- **Cut list:** the worst-performing active campaigns, with reasoning. +### Prerequisites -These are shortcuts. You can always ask the same questions in your own words. +- A project on Linkrunner that you have access to. +- The **Admin** or **Member** role on that project. **Influencers** cannot mint + MCP tokens. +- Editing tools run as the person who created the token, using that person's + project permissions. A role that cannot edit in the dashboard cannot edit + through the connector either. + +### 1. Generate a token + +1. Open the [Linkrunner dashboard](https://dashboard.linkrunner.io) and switch + to the project you want to connect. +2. Click **MCP** in the sidebar. +3. Choose what the token may do: + - **Read Linkrunner data** is always on. + - **Make changes in Linkrunner** lets the assistant use the editing tools + listed under + [What the connector can change](#what-the-connector-can-change). Turn it + off for a read-only token. + - **Read connected ad accounts** lets the assistant read your connected + Meta and Google accounts. See + [What the connector can read from your ad accounts](#what-the-connector-can-read-from-your-ad-accounts). +4. Click **Generate Token**. +5. The dashboard shows a one-time **Server URL** with the token already + embedded as a query parameter. Copy it now. The full URL will not be shown + again. + +Capabilities are fixed once a token exists. To change them, generate a new +token and revoke the old one. Tokens created before capabilities existed keep +read and change access, and no ad-account access. + + +The URL contains the token as a query parameter. Treat it like a password: +don't paste it into shared documents, screenshots, or chat threads. Revoke it +from the dashboard if it leaks, and generate a new one. + + +### 2. Connect your client + +Choose your client in the dashboard to see its setup instructions. The +token is part of the Server URL, so no separate authentication step is needed. + +![Choose a client for the Linkrunner MCP connection](/images/mcp/connect-linkrunner.png) + + + + Copy the command under **Register the Linkrunner MCP server** and run it in + a terminal: + + ```bash + claude mcp add linkrunner --scope user --transport http "" + ``` + + Start a new Claude Code session and run `/mcp` to verify the connection. + + + + These steps work in Claude Desktop and at [claude.ai](https://claude.ai). + + On Free, Pro, or Max: + + 1. Open **Customize → Connectors**. + 2. Select **+ → Add custom connector** and name it `Linkrunner`. + 3. Paste the Server URL from the dashboard. + + On Team or Enterprise, an Owner or Primary Owner first adds the Server URL + under **Organization settings → Connectors**. Members then open + **Customize → Connectors** and connect Linkrunner. + + In a chat, select **+ → Connectors** and enable Linkrunner for that + conversation. + + See [Anthropic's custom connector guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) + for current plan and organization details. + + + + Copy the command under **Register the Linkrunner MCP server** and run it in + a terminal: -## Managing tokens + ```bash + codex mcp add linkrunner --url "" + ``` + + Start a new Codex session and run `/mcp` to verify the connection. + + + + + Custom MCP apps currently work in ChatGPT on the web. ChatGPT Desktop is + not supported. Pro apps can use read and fetch tools only. Turn off + **Make changes in Linkrunner** before generating a token on Pro. Full MCP + support, including write tools, is rolling out in beta to Business and + Enterprise/Edu workspaces. + + + 1. Enable Developer mode: + - On Pro, open **Settings → Apps → Advanced settings**. + - On Business, an admin or owner enables Developer mode from + **Workspace settings → Apps → Create**. + - On Enterprise/Edu, an admin grants access under **Permissions & Roles + → Connected Data**. Enabled users then turn on Developer mode under + **Settings → Apps → Advanced settings**. + 2. Open **Settings → Apps → Create**. On Business, an admin or owner uses + **Workspace settings → Apps → Create** instead. + 3. Name the app `Linkrunner` and paste the Server URL as the MCP endpoint. + 4. Choose no authentication, then select **Scan tools** and **Create**. + 5. Test the draft in a new chat. To make it available to workspace members, + an admin or owner opens **Workspace settings → Apps → Drafts** and + selects **Publish**. + 6. Start a chat, select **Apps**, and choose Linkrunner. + + See [OpenAI's MCP apps guide](https://help.openai.com/en/articles/12584461) + for current plan and role requirements. + + + + +You only need one connection per client and project. If you manage several +Linkrunner projects, generate a token for each project and add a separate +connection with a clear name. Tokens are scoped to a single project. + + +Open a new chat or CLI session, make sure Linkrunner is enabled, and ask one of +the questions under [What you can ask](#what-you-can-ask). + +### Manage tokens Click **MCP** in the sidebar to see all active tokens for the project. For each token you can see: @@ -423,6 +576,21 @@ revoke an unused token before creating a new one. ## Security +### Sign-in connections + +- You sign in on `auth.linkrunner.io`. Before the connector gets access, a + consent page shows which app is asking, the email you signed in with, and + what the connector can do. +- The connection acts as you. It can use the projects where you are an Admin, + Owner, or Manager, and it can create new projects in your account. +- It can make the changes listed under + [What the connector can change](#what-the-connector-can-change). It cannot + read your ad accounts. +- To revoke access, disconnect or remove the Linkrunner connector in your + assistant. That ends the session. + +### Token connections + - Tokens are scoped to a single project. They cannot read or change other projects you are a member of, even when the same person created the token. - Editing tools run as the person who created the token and apply that person's @@ -437,13 +605,23 @@ revoke an unused token before creating a new one. and they are removed from every response and log. - An ad-account token can only reach accounts connected to its own project. Passing another project's account is refused. -- The connector cannot delete campaigns, funnels, domains, or projects, cannot manage - members, and cannot disconnect an ad-network account. Those stay in the +- Tokens are revocable from the dashboard at any time. The per-project cap of + 10 tokens limits the blast radius if one leaks. + + +If you only want someone to read, turn off **Make changes in Linkrunner** when +you generate their token. A read-only token does not even list the editing +tools, so the assistant cannot attempt a change with it. + + +### Both connection types + +- The connector cannot delete campaigns, funnels, domains, or projects, cannot + manage members, and cannot disconnect an ad-network account. Those stay in the dashboard. - The webhook URL is never fully readable. `get_webhook` returns the host but hides the path, because a Slack webhook path is a credential in itself. - SDK private keys, billing settings, and admin actions are not exposed. -- Tokens are revocable from the dashboard at any time. - To improve the connector, Linkrunner records basic usage for each call: the tool used, whether it worked, how long it took, the names of the arguments (not their values), the AI app you use, and the token, project, and person it @@ -453,19 +631,38 @@ revoke an unused token before creating a new one. long IDs hidden. Names and other plain text are kept as written, so avoid putting personal or confidential details in your prompts. - Usage records are kept for one year. -- Per-project token cap of 10 limits the blast radius if one leaks. - - -If you only want someone to read, turn off **Make changes in Linkrunner** when -you generate their token. A read-only token does not even list the editing -tools, so the assistant cannot attempt a change with it. - ## Troubleshooting +**The assistant says a Gmail account cannot create a project.** +You need a company email to create a project. Gmail accounts can still sign up +and be invited to existing projects. Disconnect Linkrunner, connect again, and +sign in with your company email. If you only have a personal email, contact +[support@linkrunner.io](mailto:support@linkrunner.io). + +**The assistant says your app needs a live store listing.** +An app project needs a published App Store or Play Store listing, and the +assistant will not create a website project in its place. If your app is not +published yet, come back once the listing is live. If the app is published, +paste its store link into the chat so the assistant can look it up directly. + +**The assistant says you reached the project limit.** +You can create up to 3 projects per day from an AI assistant. Try again the next +day, or create the project in the [dashboard](https://dashboard.linkrunner.io). + +**The assistant says you do not have access to a project.** +A sign-in connection can only use projects where you are an Admin, Owner, or +Manager. Ask an Admin of that project to change your role, then ask again. + +**Claude shows Connect again, or Claude Code asks you to sign in.** +The session ended, for example because the connector was disconnected. In +Claude, click **Connect** and sign in. In Claude Code, run `/mcp` and sign in. + **The client says "Couldn't reach the MCP server."** -The token may have been revoked, or the URL may be malformed. Generate a new -token, copy the full URL exactly, and reconnect Linkrunner. +On a token connection, the token may have been revoked or the URL may be +malformed. Generate a new token, copy the full URL exactly, and reconnect +Linkrunner. On a sign-in connection, check that the URL is +`https://mcp.linkrunner.io/mcp`. **The client does not show Linkrunner tools.** Make sure Linkrunner is enabled in the current chat or session. Open the @@ -474,9 +671,9 @@ inherit connector state from previous chats. **Numbers don't match the dashboard.** The connector reads the same data the dashboard does. If you see a mismatch, -check that you and the assistant are using the same date range and timezone, -and that any filters (network, platform) match. Linkrunner's ingestion is -real-time, so there's no lag to account for. +check that you and the assistant are using the same project, date range, and +timezone, and that any filters (network, platform) match. Linkrunner's ingestion +is real-time, so there's no lag to account for. **Generating a token returns "Maximum of 10 active tokens reached."** You're at the per-project cap. Revoke an unused token from the same settings @@ -493,10 +690,11 @@ Linkrunner only stores an endpoint that answers `200` or `201` to the sample payload, and it must answer directly rather than redirecting. An endpoint that returns `202` or `204` cannot be saved. -**The assistant says the token does not have the ad-accounts capability.** -The token was generated without **Read connected ad accounts**. Generate a new -token with it turned on and re-add the connector. Capabilities cannot be added -to an existing token. +**The assistant says it cannot read your ad accounts.** +Ad-account tools need a token generated with **Read connected ad accounts**. +Sign-in connections do not offer them yet. Generate a token with that option +turned on and add it as a separate connection. Capabilities cannot be added to +an existing token. **The assistant says the Meta or Google connection has expired.** The stored ad-network credential is no longer valid. Open Settings, reconnect diff --git a/introduction.mdx b/introduction.mdx index 23f66d24..b1fb8ddd 100644 --- a/introduction.mdx +++ b/introduction.mdx @@ -25,7 +25,8 @@ Watch the one-minute overview with sound on, or read on. - **Branded short links** on your own custom domain - **SKAdNetwork & privacy-safe iOS measurement** with conversion value management - **Remarketing audiences** built from on-device events -- **Webhooks, data APIs, and an MCP server** to plug attribution data into any tool +- **Webhooks, data APIs, and an [MCP server](/features/mcp)** to plug attribution data into any tool +- **Set up from Claude** with the [Linkrunner connector](/features/mcp): create your project, get your SDK token, and ask about your campaigns in a chat - **Multi-cloud, low-latency ingestion** from US, EU, and Asia ## Get Started @@ -158,7 +159,7 @@ Forward attribution data to the tools your team already uses. Receive real-time events for installs, opens, and conversions. - Query your attribution data from Claude and other AI clients. + Set up Linkrunner and query your attribution data from Claude and other AI clients. diff --git a/quickstart.mdx b/quickstart.mdx index 21b1665c..ebe25a0a 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -15,6 +15,10 @@ icon: "rocket" Then ask your agent to "integrate Linkrunner". See [Linkrunner Agent Skills](https://github.com/linkrunner-labs/skills). + + **Prefer to set up in a chat?** Add the Linkrunner connector to Claude and ask it to "set up Linkrunner attribution for my app". It creates your project and gives you the SDK token, with no dashboard steps. See [Set up and use Linkrunner from Claude](/features/mcp). + + This guide walks you through the six steps every Linkrunner integration follows. Each step links out to platform-specific instructions when you need them. For mobile SDK testing, [Open SDK Console](https://dashboard.linkrunner.io/dashboard/sdk-console/register-test-device) in the dashboard. It helps you register a test device and verify SDK events. From 5c056190c21ac7862eef54b6c33b2522b3e58442 Mon Sep 17 00:00:00 2001 From: Darshil Rathod <69842641+RathodDarshil@users.noreply.github.com> Date: Thu, 15 Oct 2026 12:58:28 +0000 Subject: [PATCH 2/4] docs(mcp): sign out before switching from a Gmail account (LIN-3708) Linkrunner keeps the browser signed in, so reconnecting alone would sign the person straight back in with Gmail. Co-Authored-By: Claude Opus 5.5 --- features/mcp.mdx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/features/mcp.mdx b/features/mcp.mdx index 5eeb364f..b120b78a 100644 --- a/features/mcp.mdx +++ b/features/mcp.mdx @@ -636,8 +636,10 @@ tools, so the assistant cannot attempt a change with it. **The assistant says a Gmail account cannot create a project.** You need a company email to create a project. Gmail accounts can still sign up -and be invited to existing projects. Disconnect Linkrunner, connect again, and -sign in with your company email. If you only have a personal email, contact +and be invited to existing projects. Linkrunner keeps you signed in, so first +sign out: open the [dashboard](https://dashboard.linkrunner.io) and sign out. +Then disconnect Linkrunner in your assistant, connect again, and sign in with +your company email. If you only have a personal email, contact [support@linkrunner.io](mailto:support@linkrunner.io). **The assistant says your app needs a live store listing.** From 61c078746333badd4a62fe5a48d95ba4e5621f06 Mon Sep 17 00:00:00 2001 From: Darshil Rathod <69842641+RathodDarshil@users.noreply.github.com> Date: Sat, 17 Oct 2026 17:36:30 +0000 Subject: [PATCH 3/4] docs(mcp): billing account choice for a new project from chat (LIN-3708) Co-Authored-By: Claude Opus 5.5 --- features/mcp.mdx | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/features/mcp.mdx b/features/mcp.mdx index b120b78a..d1e72776 100644 --- a/features/mcp.mdx +++ b/features/mcp.mdx @@ -100,8 +100,10 @@ Your assistant then works through these steps. It asks you to confirm before it The assistant calls `create_project` with the project name, company, project type (app or website), store links, report timezone, and optionally the - billing currency (USD or INR). Check these details before you approve. The - tool returns the new project ID and your SDK token. + billing currency (USD or INR). If you already have a Linkrunner billing + account, the assistant asks which one the project belongs to. Check these + details before you approve. The tool returns the new project ID and your SDK + token. Add the SDK to your app with that token. The assistant can find the guide @@ -126,8 +128,9 @@ These are the same rules the dashboard applies. - **You need a company email to create a project.** Gmail accounts can sign up and be invited to existing projects, but cannot create one. For help, contact [support@linkrunner.io](mailto:support@linkrunner.io). - **An app project needs a live App Store or Play Store listing.** You cannot set up an app that is not published yet. Come back once its listing is live. A website-only project needs the website URL instead. -- **You can create up to 3 projects per day from an AI assistant.** +- **You can create up to 3 projects per day from an AI assistant.** Only projects you created this way count. - **To use an existing project, you must be its Admin, Owner, or Manager.** +- **If you already have a billing account, you choose which one the new project uses.** On your first project, a new billing account is created for you. - New projects get the same free allowance and billing setup as projects you create in the dashboard. See [Billing](/billing/overview). ## What you can ask @@ -185,7 +188,7 @@ token decides the project, and the overview and account tools are not offered. | Tool | Use it for | |------|------------| -| `get_my_account` | The email you signed in with, and whether your account can create projects. | +| `get_my_account` | The email you signed in with, whether your account can create projects, and the billing accounts a new project can use. | | `list_projects` | Your existing projects, with their IDs, store links, and timezones. | | `find_app_in_store` | Search the App Store or Play Store by app name, or look up a store link. | | `get_sdk_configuration` | The project's SDK token, with links to the dashboard and the SDK docs. | From 7581936a1c4d27f4639700f56f314ad71c5abd9d Mon Sep 17 00:00:00 2001 From: Darshil Rathod <69842641+RathodDarshil@users.noreply.github.com> Date: Sat, 17 Oct 2026 19:36:26 +0000 Subject: [PATCH 4/4] docs(mcp): tell agents to guide people through adding the connector (LIN-3708) Co-Authored-By: Claude Opus 5.5 --- docs.json | 1 + 1 file changed, 1 insertion(+) diff --git a/docs.json b/docs.json index 0568f540..4c6c8c28 100644 --- a/docs.json +++ b/docs.json @@ -25,6 +25,7 @@ "markdown": { "instructions": [ "Linkrunner has a remote MCP server at https://mcp.linkrunner.io/mcp. People sign in to Linkrunner in a browser popup (OAuth), so there is no token to copy. New users sign up in the same popup.", + "If a person asks you to sign them up, log them in, or set Linkrunner up and you have no Linkrunner tools, do not send them to the website: tell them to add the connector and walk them through it. In Claude: Customize (or Settings), Connectors, Add custom connector, name Linkrunner, URL https://mcp.linkrunner.io/mcp, leave the OAuth fields empty, click Connect, sign in or sign up in the popup, click Allow, then turn the connector on for the chat and ask again.", "Before sign-in, only get_linkrunner_overview and search_documentation work. Any other tool asks the person to sign in first.", "To set a person up: connect the server, then call get_my_account, list_projects, find_app_in_store (confirm the right app with the person), and create_project. create_project returns the project ID and the SDK token. Install the SDK with that token. get_sdk_configuration returns the token again later.", "Rules: a company email is needed to create a project (Gmail accounts cannot), an app project needs a live App Store or Play Store listing, a person can create up to 3 projects per day from an AI assistant, and using an existing project needs the Admin, Owner or Manager role.",