From 1d4f34c5a1a86ba6cbeac4e25e5d0be46e7dd5cf Mon Sep 17 00:00:00 2001 From: Stan Rymkiewicz <149009265+stan-rym@users.noreply.github.com> Date: Fri, 23 Oct 2026 09:59:28 -0400 Subject: [PATCH] Docs: set up Meta Muse and Grok Bot through your own endpoint Muse and Grok Bot run in their maker's cloud and add an MCP server with 1 secret, so both pages walk through deploying your own endpoint (now with a Deploy to Vercel button that sets the Root Directory) and adding it with MCP_AUTH_TOKEN as a bearer token. hosted.md gets the button and a short section for apps that run in the cloud, and the README links both pages. Co-Authored-By: Claude Opus 5.5 --- README.md | 5 +-- docs/clients-grok.md | 57 ++++++++++++++++++++++++++++++++++ docs/clients-muse.md | 54 ++++++++++++++++++++++++++++++++ docs/hosted.md | 6 +++- docs/platforms-linkedin-ads.md | 2 +- 5 files changed, 120 insertions(+), 4 deletions(-) create mode 100644 docs/clients-grok.md create mode 100644 docs/clients-muse.md diff --git a/README.md b/README.md index 71b3f5b..c1f0b34 100644 --- a/README.md +++ b/README.md @@ -190,8 +190,9 @@ local change journal (`~/.adwarp/changelog.jsonl`) for later lift analysis. The [install guide](https://adwarp.dev/docs/install) on adwarp.dev has these steps too, with a setup page for each client: [Claude Code](https://adwarp.dev/docs/clients/claude-code), [Claude Desktop](https://adwarp.dev/docs/clients/claude-desktop), -[Cursor](https://adwarp.dev/docs/clients/cursor), [Codex](https://adwarp.dev/docs/clients/codex) -and the [CLI](https://adwarp.dev/docs/clients/cli). +[Cursor](https://adwarp.dev/docs/clients/cursor), [Codex](https://adwarp.dev/docs/clients/codex), +the [CLI](https://adwarp.dev/docs/clients/cli), and, through your own endpoint, [Meta Muse](https://adwarp.dev/docs/clients/muse) +and [Grok Bot](https://adwarp.dev/docs/clients/grok). There are two ways to install Adwarp: diff --git a/docs/clients-grok.md b/docs/clients-grok.md new file mode 100644 index 0000000..0db3aa6 --- /dev/null +++ b/docs/clients-grok.md @@ -0,0 +1,57 @@ +--- +title: Grok Bot +description: "Connect xAI's Grok Bot to your own Adwarp endpoint with 1 header, then check that it works." +order: 20 +--- + +Grok Bot, xAI's personal agent, runs on a cloud computer, so it can't start Adwarp on your machine or reach a server there. It connects over the internet to your own copy of the [hosted endpoint](./hosted.md) instead, and gets the LinkedIn tools that endpoint serves. The Google Ads tools need the local server, so they don't run in Grok yet. + +[Create a LinkedIn app](./linkedin-app.md) and [authenticate](./install.md#authenticate) first. + +## Deploy your endpoint + +Grok Bot adds a custom MCP server with 1 header. The shared endpoint at `mcp.adwarp.dev` takes 3 credential headers, so deploy your own, which takes 1 `Authorization` header carrying your `MCP_AUTH_TOKEN`. + +1. Print your LinkedIn values: `npx -y adwarp auth export`. +2. Make a token: `openssl rand -hex 32`. +3. Click [Deploy to Vercel](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fadwarp-dev%2Fadwarp&root-directory=apps%2Fweb&project-name=adwarp-mcp&repository-name=adwarp-mcp&env=ADWARP_LINKEDIN_CLIENT_ID,ADWARP_LINKEDIN_CLIENT_SECRET,ADWARP_LINKEDIN_REFRESH_TOKEN,MCP_AUTH_TOKEN&envDescription=LinkedIn%20app%20values%20from%20npx%20-y%20adwarp%20auth%20export%20and%20a%20long%20random%20MCP_AUTH_TOKEN%20that%20your%20AI%20app%20sends%20as%20a%20bearer%20token.&envLink=https%3A%2F%2Fadwarp.dev%2Fdocs%2Fhosted%23self-host-on-vercel). It copies this repo into your GitHub account, sets the Root Directory to `apps/web` and asks for these 4 values: + +| Variable | Value | +| --- | --- | +| `ADWARP_LINKEDIN_CLIENT_ID` | from `auth export` | +| `ADWARP_LINKEDIN_CLIENT_SECRET` | from `auth export` | +| `ADWARP_LINKEDIN_REFRESH_TOKEN` | from `auth export` | +| `MCP_AUTH_TOKEN` | the token you made | + +Your endpoint is `https://.vercel.app/api/mcp`. If Vercel Authentication covers production in your team's Deployment Protection settings, turn it off for production, or Grok can't reach the endpoint. To set the project up by hand instead, follow [Self-host on Vercel](./hosted.md#self-host-on-vercel). + +## Add it to your bot + +Send your bot this message with your endpoint's URL. Say "custom MCP server", or the bot may look for a plugin in its catalog instead. + +``` +Add a custom MCP server called adwarp at https://.vercel.app/api/mcp +``` + +When it asks for a key, give it the header: + +| Field | Value | +| --- | --- | +| Header name | `Authorization` | +| Header value | `Bearer ` | + +Grok Bot stores the header on the server entry, and your LinkedIn client secret stays in your Vercel project. + +## Check that it works + +Ask your bot something read-only: "List my LinkedIn ad accounts" or "How did my LinkedIn account do in the last 30 days?" + +Writes stay in your hands. Adwarp creates campaigns and ads as drafts, and sets a campaign or an ad ACTIVE only when you explicitly ask. + +## Connectors on grok.com + +Custom connectors on grok.com sign in with OAuth, which the endpoint doesn't support yet. Use Grok Bot until it does. + +## What runs in Grok + +Every LinkedIn tool your endpoint serves: accounts, targeting and audience sizing, conversions, campaigns and ads, reporting and Ad Library search. CSV uploads, Salesforce and HubSpot audiences, the change journal and lift tools, and every Google Ads tool need your machine, so run those in [Claude Code](./clients-claude-code.md), [Codex](./clients-codex.md), [Cursor](./clients-cursor.md) or the [CLI](./clients-cli.md). See [Hosted limitations](./hosted.md#hosted-limitations). diff --git a/docs/clients-muse.md b/docs/clients-muse.md new file mode 100644 index 0000000..d959061 --- /dev/null +++ b/docs/clients-muse.md @@ -0,0 +1,54 @@ +--- +title: Meta Muse +description: "Connect Meta Muse to your own Adwarp endpoint with 1 bearer token, then check that it works." +order: 19 +--- + +Meta Muse runs on a computer in Meta's cloud, so it can't start Adwarp on your machine or reach a server there. It connects over the internet to your own copy of the [hosted endpoint](./hosted.md) instead, and gets the LinkedIn tools that endpoint serves. The Google Ads tools need the local server, so they don't run in Muse yet. + +[Create a LinkedIn app](./linkedin-app.md) and [authenticate](./install.md#authenticate) first. + +## Deploy your endpoint + +Muse adds a custom MCP server with 1 secret, a bearer token. The shared endpoint at `mcp.adwarp.dev` takes 3 credential headers, so deploy your own, which takes 1 `MCP_AUTH_TOKEN`. + +1. Print your LinkedIn values: `npx -y adwarp auth export`. +2. Make a token: `openssl rand -hex 32`. +3. Click [Deploy to Vercel](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fadwarp-dev%2Fadwarp&root-directory=apps%2Fweb&project-name=adwarp-mcp&repository-name=adwarp-mcp&env=ADWARP_LINKEDIN_CLIENT_ID,ADWARP_LINKEDIN_CLIENT_SECRET,ADWARP_LINKEDIN_REFRESH_TOKEN,MCP_AUTH_TOKEN&envDescription=LinkedIn%20app%20values%20from%20npx%20-y%20adwarp%20auth%20export%20and%20a%20long%20random%20MCP_AUTH_TOKEN%20that%20your%20AI%20app%20sends%20as%20a%20bearer%20token.&envLink=https%3A%2F%2Fadwarp.dev%2Fdocs%2Fhosted%23self-host-on-vercel). It copies this repo into your GitHub account, sets the Root Directory to `apps/web` and asks for these 4 values: + +| Variable | Value | +| --- | --- | +| `ADWARP_LINKEDIN_CLIENT_ID` | from `auth export` | +| `ADWARP_LINKEDIN_CLIENT_SECRET` | from `auth export` | +| `ADWARP_LINKEDIN_REFRESH_TOKEN` | from `auth export` | +| `MCP_AUTH_TOKEN` | the token you made | + +Your endpoint is `https://.vercel.app/api/mcp`. If Vercel Authentication covers production in your team's Deployment Protection settings, turn it off for production, or Muse can't reach the endpoint. To set the project up by hand instead, follow [Self-host on Vercel](./hosted.md#self-host-on-vercel). + +## Add it in Muse + +Send Muse this message with your endpoint's URL: + +``` +Add a custom MCP server called adwarp at https://.vercel.app/api/mcp +``` + +Then answer its questions: + +| Muse asks | Answer | +| --- | --- | +| Transport | HTTP | +| Auth | Bearer token | +| Key | your `MCP_AUTH_TOKEN` | + +Type the token into Muse's secure prompt, never into the chat, where it would stay in your history. Muse keeps it in its credential store, and your LinkedIn client secret stays in your Vercel project. + +## Check that it works + +Ask Muse something read-only: "List my LinkedIn ad accounts" or "How did my LinkedIn account do in the last 30 days?" + +Writes stay in your hands. Adwarp creates campaigns and ads as drafts, and sets a campaign or an ad ACTIVE only when you explicitly ask. Muse's own settings can also make it ask before every action. + +## What runs in Muse + +Every LinkedIn tool your endpoint serves: accounts, targeting and audience sizing, conversions, campaigns and ads, reporting and Ad Library search. CSV uploads, Salesforce and HubSpot audiences, the change journal and lift tools, and every Google Ads tool need your machine, so run those in [Claude Code](./clients-claude-code.md), [Codex](./clients-codex.md), [Cursor](./clients-cursor.md) or the [CLI](./clients-cli.md). See [Hosted limitations](./hosted.md#hosted-limitations). diff --git a/docs/hosted.md b/docs/hosted.md index f661609..1790335 100644 --- a/docs/hosted.md +++ b/docs/hosted.md @@ -65,7 +65,7 @@ The clean split for teams: your MCP client's config holds the credentials (the h Run your own instance so credentials never touch shared infrastructure, and so you also get a private, environment-configured tenant. 1. Get your environment values locally: `npx -y adwarp auth export`. -2. Deploy `apps/web` to Vercel, with the project Root Directory set to `apps/web`. +2. Deploy `apps/web` to Vercel, with the project Root Directory set to `apps/web`. [Deploy to Vercel](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fadwarp-dev%2Fadwarp&root-directory=apps%2Fweb&project-name=adwarp-mcp&repository-name=adwarp-mcp&env=ADWARP_LINKEDIN_CLIENT_ID,ADWARP_LINKEDIN_CLIENT_SECRET,ADWARP_LINKEDIN_REFRESH_TOKEN,MCP_AUTH_TOKEN&envDescription=LinkedIn%20app%20values%20from%20npx%20-y%20adwarp%20auth%20export%20and%20a%20long%20random%20MCP_AUTH_TOKEN%20that%20your%20AI%20app%20sends%20as%20a%20bearer%20token.&envLink=https%3A%2F%2Fadwarp.dev%2Fdocs%2Fhosted%23self-host-on-vercel) does this in 1 click: it copies the repo into your GitHub account, sets the Root Directory and asks for the variables in step 3. 3. In the Vercel project settings, add the environment variables that `auth export` printed (`ADWARP_LINKEDIN_CLIENT_ID`, `ADWARP_LINKEDIN_CLIENT_SECRET`, `ADWARP_LINKEDIN_REFRESH_TOKEN`, `ADWARP_LINKEDIN_VERSION`) plus a strong `MCP_AUTH_TOKEN`. In the Deployment Protection settings, disable Vercel Authentication for production (or add a protection-bypass secret), otherwise MCP clients cannot reach the endpoint. 4. Your MCP endpoint is `https://.vercel.app/api/mcp`. Connect with the secret in the header: @@ -77,3 +77,7 @@ claude mcp add --transport http adwarp https://.vercel.app/api/mcp \ Requests carrying `MCP_AUTH_TOKEN` use the environment credentials (your tenant). Requests carrying the `X-Adwarp-Linkedin-*` headers use the caller's credentials instead, so a single self-hosted instance can serve your whole team, each member on their own LinkedIn app. The app serves only the endpoint. Its other paths, such as `/` and `/docs`, redirect to adwarp.dev. + +## Apps that run in the cloud + +Some AI apps run on a computer in their maker's cloud, so they can't reach a local server, and they add a custom MCP server with 1 secret instead of 3 headers. Point them at your own deployment with its `MCP_AUTH_TOKEN` as a bearer token. See the setup for [Meta Muse](./clients-muse.md) and [Grok Bot](./clients-grok.md). diff --git a/docs/platforms-linkedin-ads.md b/docs/platforms-linkedin-ads.md index 3b91db1..4665f72 100644 --- a/docs/platforms-linkedin-ads.md +++ b/docs/platforms-linkedin-ads.md @@ -1,7 +1,7 @@ --- title: LinkedIn Ads description: "What Adwarp does on LinkedIn Ads, area by area, with the tools behind each one." -order: 19 +order: 21 --- Adwarp runs LinkedIn Ads through your own developer app, with tools for targeting, audiences, campaigns, reporting, competitor ads and the change journal. Everything it creates starts as a draft. A campaign or a single ad goes live only when you explicitly ask Adwarp to set it ACTIVE, or when you switch it on in Campaign Manager.