# Connect your AI agent

> Add the NeuroPage MCP server to claude.ai, Claude Code, Claude Desktop, ChatGPT, Codex, Cursor, Grok, Grok Bot or VS Code, and see what each tool does and costs.

NeuroPage MCP connects an AI assistant such as Claude, ChatGPT, Cursor or Codex to your NeuroPage workspace. From a chat you can set up a brand and a template, make a personalized landing page for each lead, write the emails and LinkedIn messages, send leads to Instantly, and see who viewed their page.

**Server URL:** `https://neuropage.io/api/mcp` (Streamable HTTP)

## Connect

There are two ways to connect:

- **Sign in with NeuroPage (OAuth), recommended.** No key. The connection acts as you, in every workspace you belong to, and you can disconnect it any time under **Settings, API & MCP**.
- **API key.** Send `Authorization: Bearer np_live_YOUR_KEY`. A key belongs to one workspace, can have a monthly credit cap, and is shown once when you create it under **Settings, API & MCP**.

### claude.ai and Claude Desktop

1. Open **Settings, Connectors** and click **Add custom connector**.
2. Name it NeuroPage and paste `https://neuropage.io/api/mcp` as the URL.
3. Click **Connect**, sign in to NeuroPage, and click **Allow**.

The connector acts as you, in every workspace you belong to. If you are in several (an agency with a workspace per client), Claude asks which client each request is for. You can disconnect it any time under **Settings, API & MCP**.

### Claude Desktop with an API key

If you prefer a key to signing in, open **Settings, Developer, Edit Config** and add NeuroPage to `claude_desktop_config.json`, then restart Claude Desktop. This needs Node.js on your computer, because `mcp-remote` runs through `npx`.

```json
{
  "mcpServers": {
    "neuropage": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://neuropage.io/api/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer np_live_YOUR_KEY"
      }
    }
  }
}
```

The header is written as `Authorization:${AUTH_HEADER}` with no space on purpose: Claude Desktop on Windows splits arguments on spaces, so the space lives in the `env` value instead.

### ChatGPT

Custom connectors in the ChatGPT app need Developer mode, which depends on your ChatGPT plan and workspace settings, and the menu names can change:

1. In ChatGPT, open **Settings**, find **Apps & Connectors**, and turn on **Developer mode** under the advanced settings.
2. Create a connector named NeuroPage with `https://neuropage.io/api/mcp` as the MCP server URL.
3. Choose **OAuth** as the authentication, sign in to NeuroPage, and click **Allow**.

The connector acts as you, like the claude.ai connector. No API key is needed.

### Claude Code

Sign in with your NeuroPage account: add the server without a key, then run `/mcp` in Claude Code and choose NeuroPage to sign in.

```bash
claude mcp add --transport http neuropage https://neuropage.io/api/mcp
```

Or use an API key, which is pinned to one workspace:

Run this once in your terminal, with your key:

```bash
claude mcp add --transport http neuropage https://neuropage.io/api/mcp --header "Authorization: Bearer np_live_YOUR_KEY"
```

To share the setup with your team without sharing the key, put this in `.mcp.json` at the root of the project and set `NEUROPAGE_API_KEY` in each person's environment:

```json
{
  "mcpServers": {
    "neuropage": {
      "type": "http",
      "url": "https://neuropage.io/api/mcp",
      "headers": {
        "Authorization": "Bearer ${NEUROPAGE_API_KEY}"
      }
    }
  }
}
```

### Codex

For Codex, OpenAI's coding agent, keep the key in an environment variable:

```bash
export NEUROPAGE_API_KEY=np_live_YOUR_KEY
codex mcp add neuropage --url https://neuropage.io/api/mcp --bearer-token-env-var NEUROPAGE_API_KEY
```

### Cursor

[Add NeuroPage to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=neuropage&config=eyJ1cmwiOiJodHRwczovL25ldXJvcGFnZS5pby9hcGkvbWNwIiwiaGVhZGVycyI6eyJBdXRob3JpemF0aW9uIjoiQmVhcmVyIG5wX2xpdmVfWU9VUl9LRVkifX0%3D). After it opens, replace `np_live_YOUR_KEY` with your key in Cursor's MCP settings.

Or add it to `~/.cursor/mcp.json` yourself:

```json
{
  "mcpServers": {
    "neuropage": {
      "url": "https://neuropage.io/api/mcp",
      "headers": {
        "Authorization": "Bearer np_live_YOUR_KEY"
      }
    }
  }
}
```

### VS Code

Add this to `.vscode/mcp.json`. VS Code asks for the key once and stores it securely.

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "neuropage-key",
      "description": "NeuroPage API key",
      "password": true
    }
  ],
  "servers": {
    "neuropage": {
      "type": "http",
      "url": "https://neuropage.io/api/mcp",
      "headers": {
        "Authorization": "Bearer ${input:neuropage-key}"
      }
    }
  }
}
```

### Grok

The Grok command-line tool adds the server the same way as Claude Code. Run this once, with your key:

```bash
grok mcp add --transport http neuropage https://neuropage.io/api/mcp --header "Authorization: Bearer np_live_YOUR_KEY"
```

### Grok Bot

Ask your Bot to add a custom MCP server with the URL `https://neuropage.io/api/mcp`. In the desktop app, go to **Connect apps, Add a custom connector, Remote HTTPS** and paste the URL.

Untested: we have not yet confirmed that the NeuroPage sign-in completes in Grok Bot.

### OpenAI Responses API

In the Responses API, add NeuroPage as a remote MCP tool and send your key in `headers`. Here the read tools run on their own and anything that writes or spends credits comes back as an approval request first:

```js
import OpenAI from "openai";

const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-5",
  tools: [
    {
      type: "mcp",
      server_label: "neuropage",
      server_url: "https://neuropage.io/api/mcp",
      headers: { Authorization: "Bearer np_live_YOUR_KEY" },
      // Reads run on their own; anything that writes or spends credits
      // comes back as an approval request first.
      require_approval: { never: { tool_names: ["list_workspaces", "get_workspace", "list_brands", "get_brand", "list_templates", "get_template", "get_job", "list_assets", "get_asset_stats", "get_company_profile", "list_media", "list_campaigns", "list_event_subscriptions", "get_campaign", "list_leads", "list_columns", "check_variables", "list_instantly_campaigns"] } },
    },
  ],
  input: "Check my NeuroPage workspace and tell me what is missing.",
});

console.log(response.output_text);
```

### Other MCP clients

Use the server URL `https://neuropage.io/api/mcp`. A client that supports OAuth finds the sign-in itself: the protected resource metadata is at `https://neuropage.io/.well-known/oauth-protected-resource` and the authorization server metadata at `https://neuropage.io/.well-known/oauth-authorization-server`. NeuroPage advertises PKCE with `S256`. The scopes are `email` and `profile`.

If your client has no OAuth support, send an API key in the `Authorization` header. For Claude Desktop with a key, see Claude Desktop with an API key above. From code, tools such as Clay, n8n and Make use [the REST API](https://docs.neuropage.io/quickstart).

## Try it

Ask your agent, in this order:

1. "Set up a NeuroPage brand from acme.com and show me the logo and colours it found."
2. "Make NeuroPage landing pages for these 3 LinkedIn profiles with that brand: <3 profile URLs>."
3. "Which of those leads have viewed their page?"

The agent checks your workspace, tells you what the pages will cost before it spends anything, waits for the pages, and gives you a table of leads and page URLs.

More prompts:

- "Import my Instantly campaign <name> into a new NeuroPage campaign, make pages for the first 3 leads, and show me the cost first."
- "Write the emails and LinkedIn messages for the leads in <campaign>, then send them to Instantly with their page URLs."
- "Which {{variables}} in my template have no column yet?"

## How the agent behaves

The server sends your agent these rules when it connects.

- **Workspace first.** It calls `list_workspaces` first. If you belong to several workspaces (an agency with a workspace per client), it asks which client you mean and never guesses.
- **Quotes before it spends.** Before anything that spends credits, it tells you the most it can cost and how many credits you have left. The tools that spend take `dry_run: true`, which returns the cost and changes nothing. After a run it reports the credits charged.
- **3 leads first.** It runs on 3 leads, shows you the result, and asks before running the rest.
- **It asks before big changes:** creating a campaign, importing or generating for more than a few leads, sending leads to Instantly, deleting media.
- **No plan, no writes.** If a workspace has no plan, reads still work and every write returns `plan_required` with a link to fix it. The agent tells you and shows the link.
- **Sandbox.** If a workspace has `sandbox: true`, it is a shared demo workspace with low limits that other developers can read, so the agent says so and sends no real lead data to it. [Contact us for sandbox access](https://neuropage.io/contact). See [Sandbox and plans](https://docs.neuropage.io/sandbox-and-plans).

## Tools

Read tools carry `readOnlyHint` and work on a workspace without a plan. Write tools return `plan_required` until the workspace has one. Only the tools marked Yes spend credits, and each of them takes `dry_run`; the rest are free to call. What each one costs and when it is refunded: [Credits and limits](https://docs.neuropage.io/credits-and-limits).

### Set up

| Tool | Access | Spends credits | `dry_run` |
|---|---|---|---|
| `list_workspaces` | Read | No | - |
| `create_workspace` | Write | No | - |
| `get_workspace` | Read | No | - |
| `get_company_profile` | Read | No | - |
| `propose_company_profile_update` | Write | No | - |
| `apply_company_profile_update` | Write | No | - |

### Brand and template

| Tool | Access | Spends credits | `dry_run` |
|---|---|---|---|
| `list_brands` | Read | No | - |
| `get_brand` | Read | No | - |
| `create_brand_from_website` | Write | No | - |
| `update_brand` | Write | No | - |
| `list_templates` | Read | No | - |
| `get_template` | Read | No | - |
| `create_template` | Write | No | - |
| `update_template` | Write | No | - |
| `set_section_images` | Write | No | - |

### Pages from LinkedIn URLs

| Tool | Access | Spends credits | `dry_run` |
|---|---|---|---|
| `generate_assets` | Write | Yes: up to `cost_per_asset` per new page; a reused page is free | Yes |
| `get_job` | Read | No | - |
| `list_assets` | Read | No | - |
| `get_asset_stats` | Read | No | - |

### Campaigns and leads

| Tool | Access | Spends credits | `dry_run` |
|---|---|---|---|
| `list_campaigns` | Read | No | - |
| `get_campaign` | Read | No | - |
| `create_campaign` | Write | No | Yes |
| `update_campaign` | Write | No | - |
| `import_leads` | Write | Yes: 1 credit per new lead analysed | Yes |
| `list_leads` | Read | No | - |
| `list_columns` | Read | No | - |
| `create_column` | Write | No | - |
| `set_cell_values` | Write | No | - |
| `run_research` | Write | Yes: per lead and research column; `list_columns` has prices | Yes |
| `check_variables` | Read | No | - |
| `generate_pages` | Write | Yes: 2 credits a page | Yes |

### Messages

| Tool | Access | Spends credits | `dry_run` |
|---|---|---|---|
| `update_message_settings` | Write | No | - |
| `generate_messages` | Write | Yes: 0.5 credits a lead | Yes |
| `set_messages` | Write | No | - |

### Media library

| Tool | Access | Spends credits | `dry_run` |
|---|---|---|---|
| `list_media` | Read | No | - |
| `upload_media` | Write | No | - |
| `create_media_upload` | Write | No | - |
| `complete_media_upload` | Write | No | - |
| `delete_media` | Write | No | - |

### Instantly

| Tool | Access | Spends credits | `dry_run` |
|---|---|---|---|
| `list_instantly_campaigns` | Read | No | - |
| `import_from_instantly` | Write | Yes: up to 1 credit per new lead analysed | Yes |
| `send_to_instantly` | Write | No | - |

### Events

| Tool | Access | Spends credits | `dry_run` |
|---|---|---|---|
| `subscribe_events` | Write | No | - |
| `list_event_subscriptions` | Read | No | - |
| `unsubscribe_events` | Write | No | - |

Notes:

- Every tool except `list_workspaces` and `create_workspace` takes an optional `workspace`: a slug from `list_workspaces`. With an API key it is always the key's own workspace.
- `create_workspace` works with OAuth sign-in only, at most 3 a day. Only the first workspace you create starts with 250 credits; every later one starts at 0. It is read-only until you start a plan in the app.
- `generate_assets` takes 1 to 25 LinkedIn URLs and returns a job. Quote it first with `dry_run: true`: the answer gives the credits and says which leads already have a page. Then follow the job with `get_job`, which waits up to 50 seconds for a change.
- `import_leads` takes up to 500 leads a call.
- A tool that has no `dry_run` refuses it as an unknown argument instead of running for real.

## Getting told when a page is ready

Poll `get_job` (it waits up to 50 seconds for a change), or have NeuroPage call you. `subscribe_events` registers an https callback URL for `page.ready` and `job.failed` and returns a signing secret once. `list_event_subscriptions` and `unsubscribe_events` manage them. Webhooks you create in the app under **Integrations, Webhooks** keep working for `lead.ready` and page activity, and `lead.ready` needs a campaign whose **Autopilot, Send** stage is that webhook. See [Webhooks](https://docs.neuropage.io/webhooks).

## Connection issues

- **401 `unauthorized`:** the key or token is missing, unknown or revoked. Reconnect, or send a key from **Settings, API & MCP**.
- **404 `not_found` over OAuth:** the workspace slug is not one of yours, or you are not in any workspace yet. Create one in the app, or ask the agent to use `create_workspace`.
- **403 `plan_required`:** the workspace has no paid plan or trial with a card. Reads still work. Open the `fix.url` in the error.
- **402 `insufficient_credits` or `spend_cap_reached`:** nothing was charged. Add credits, send fewer leads, or raise the key's monthly cap.
- **429 `rate_limited`:** wait the `Retry-After` seconds. The limits are 60 requests a minute per key or signed-in user and 2 running page jobs per workspace; new pages are capped at 200 an hour and 1,000 a day. A sandbox key gets 10 requests a minute, 10 new pages a day and 1 running job at a time. Every limit and its error: [Credits and limits](https://docs.neuropage.io/credits-and-limits).

Every error code: [Errors](https://docs.neuropage.io/errors). Every endpoint: [the API reference](https://docs.neuropage.io/reference).
