# Scouty API and MCP server: Get started

Connect your AI assistant to Scouty once, then ask about your creator campaigns in plain language. It works inside your own Scouty workspace, with the permissions you give it, and it can only do what you allow.

## New to connectors?

A **connector** lets an AI assistant such as Claude or ChatGPT use another service for you. You add Scouty once, sign in, and choose what it may do. After that you can ask "which of my campaigns are live, and who has signed on?" and the assistant looks it up in Scouty instead of guessing. Scouty's connector is an **MCP server**, which is the standard most assistants use for this.

## Before you start

| You need | Why |
|---|---|
| A Scouty workspace you can sign in to | The assistant works inside it, as you |
| An assistant that allows custom connectors, or a developer tool | Everyday assistants: Claude, ChatGPT, Le Chat. Developer tools: Claude Code, Cursor, VS Code, Codex, and others |
| Two minutes | Most apps take four or five clicks |

## Which address to paste

Every app below needs the same one address:

```text
https://api.tryscouty.com/mcp
```

Everything else, for developers:

| | |
|---|---|
| REST API | `https://api.tryscouty.com/v1` |
| OpenAPI | `https://api.tryscouty.com/v1/openapi.json` |
| These docs, as Markdown | `https://api.tryscouty.com/v1/docs` |
| These docs, as a page | `https://docs.tryscouty.com` |
| Auth | Sign in (OAuth), or `Authorization: Bearer <token>` |

## Everyday assistants, no setup files

Each app signs you in to Scouty the same way. A Scouty page opens and shows the app's name and where it sends you back to. On that page:

- Sign in with Google, if asked.
- Choose your **workspace**.
- Choose what the app may do, and how long access lasts: **30 days**, **90 days**, **1 year**, or **Indefinitely**.
- Press **Allow**.

### Claude

Works on claude.ai and the Claude desktop app.

1. **Open your connectors.** Go to **Settings → Connectors**. In some versions it is under **Customize → Connectors**.
2. **Add a custom connector.** Click **Add custom connector**.
3. **Paste the address.** Name it `Scouty`. Paste `https://api.tryscouty.com/mcp` as the URL. Click **Add**.
4. **Sign in.** Click **Connect** next to Scouty. Sign in, choose your workspace, and press **Allow**.
5. **Turn it on.** In a chat, open the tools menu and turn **Scouty** on.

### ChatGPT

1. **Turn on Developer mode.** Go to **Settings → Apps & Connectors → Advanced settings** and turn on **Developer mode**.
2. **Create the connector.** Back in **Apps & Connectors**, click **Create**.
3. **Fill in the form.** Name it `Scouty`, with the description `My creator campaigns`. Paste `https://api.tryscouty.com/mcp` as the **MCP server URL**, and set **Authentication** to **OAuth**. Click **Create**.
4. **Sign in.** Sign in to Scouty, choose your workspace, and press **Allow**.
5. **Turn it on.** In a new chat, open the **+** menu and turn **Scouty** on.

### Le Chat

Mistral's assistant.

1. **Open your connectors.** Go to **Intelligence → Connectors**.
2. **Add a custom connector.** Click **Add connector**, then choose **Custom MCP connector**.
3. **Paste the address.** Name it `Scouty`. Paste `https://api.tryscouty.com/mcp` as the URL. Click **Connect**.
4. **Sign in.** Sign in to Scouty, choose your workspace, and press **Allow**.
5. **Turn it on.** In a chat, turn **Scouty** on from the tools menu.

> **Note:** If Le Chat asks for an API key or a header instead of opening a sign-in page, use a token. See [If an app asks for a token](https://docs.tryscouty.com/control#if-an-app-asks-for-a-token).

## Developer tools

Each tool below can sign in with the address alone.

> **Tip:** Would you rather use a token? Every tool below has a tile on the **Agents** page. See [If an app asks for a token](https://docs.tryscouty.com/control#if-an-app-asks-for-a-token).

### Claude Code

1. **Add the server.** Run `claude mcp add --transport http scouty https://api.tryscouty.com/mcp`
2. **Open the MCP menu.** Start Claude Code and type `/mcp`.
3. **Authenticate.** Choose **scouty**, then **Authenticate**. Your browser opens.
4. **Sign in.** Sign in, choose your workspace, and press **Allow**.
5. **Check it works.** Ask: "Call scouty_whoami and tell me what you can do."

With a token instead: press the **Claude Code** tile on the **Agents** page. It writes `.mcp.json` with `${SCOUTY_TOKEN}` in it, never the token.

> **Important:** Do not pass the token with `claude mcp add --header`. That puts it in your shell history.

### Cursor

Put this in `~/.cursor/mcp.json` (or `.cursor/mcp.json` in the project):

```json
{ "mcpServers": { "scouty": { "url": "https://api.tryscouty.com/mcp" } } }
```

1. **Save the file.**
2. **Open the MCP settings.** Go to **Cursor Settings → MCP** (called **Tools & MCP** in some versions).
3. **Start sign-in.** Next to **scouty**, click the sign-in prompt. Your browser opens.
4. **Sign in.** Sign in, choose your workspace, and press **Allow**.

### VS Code

1. **Add the server.** Open the Command Palette (**Cmd+Shift+P** on a Mac, **Ctrl+Shift+P** elsewhere) and run **MCP: Add Server**.
2. **Paste the address.** Choose **HTTP**. Paste `https://api.tryscouty.com/mcp`. Name it `scouty`.
3. **Start the server.** When VS Code asks to sign in, click **Allow**.
4. **Sign in.** Sign in to Scouty, choose your workspace, and press **Allow**.
5. **Use it.** The Scouty tools appear in **Chat** in agent mode.

### Codex

1. **Add the server.** Run `codex mcp add scouty --url https://api.tryscouty.com/mcp`
2. **Open sign-in if needed.** If no sign-in page opens, run `codex mcp login scouty`.
3. **Sign in.** Sign in, choose your workspace, and press **Allow**.

> **Note:** Codex changes its commands often. If one looks different, check Codex's own MCP page. The token route always works: press the **Codex** tile on the **Agents** page.

### Windsurf, Gemini CLI, and opencode

Use a token. Press the tile for your tool on the **Agents** page and paste what it copies into the tool. See [If an app asks for a token](https://docs.tryscouty.com/control#if-an-app-asks-for-a-token).

### Any other client

Most MCP clients take one of two shapes. The key names differ by client, so check its MCP page.

**Sign-in**, when the client supports OAuth:

```json
{ "mcpServers": { "scouty": { "url": "https://api.tryscouty.com/mcp" } } }
```

**Token**, when it does not. Keep the token in the `SCOUTY_TOKEN` environment variable and use your client's own way of referring to it:

```json
{
  "mcpServers": {
    "scouty": {
      "url": "https://api.tryscouty.com/mcp",
      "headers": { "Authorization": "Bearer ${SCOUTY_TOKEN}" }
    }
  }
}
```

**No MCP client at all?** Use REST:

```bash
curl -H "Authorization: Bearer $SCOUTY_TOKEN" https://api.tryscouty.com/v1/me
```

## After you connect

1. **Turn Scouty on.** If your app has a tools menu, turn **Scouty** on in the chat.
2. **Start with a read.** Ask for something that only reads: "Using Scouty, list my campaigns and tell me which ones are live."
3. **Then let it prepare work.** Ask it to prepare work for you to approve:

| Ask | What happens |
|---|---|
| "Who has signed on to my newest campaign, and how far through activation is each one?" | Reads only |
| "Draft a new campaign for our spring launch. Show it to me before you create it." | Creates a draft once you say yes. A draft reaches nobody |
| "Tighten the deliverables on that campaign and show me the change first." | Saves it once you say yes. A live campaign's change waits for the team's review |
| "When I confirm, ask the team to publish it." | Asks the team. The team reviews and publishes every campaign |

> **Note:** Changes need a permission you ticked when you connected. Without one, the assistant can only read.