# Scouty API and MCP server: Control and troubleshooting

## Staying in control

| | |
|---|---|
| It acts as you | It works in your workspace with the permissions you ticked. **Activity** on the Agents page shows what it did |
| Read only | Leave **Let it act** unticked when you connect. It can then read and nothing else |
| Access runs out | After the length you chose: 30 days, 90 days, or 1 year. The app then asks you to connect again. Indefinitely lasts until you revoke it |
| Disconnect | **Settings → Agents**, then **Revoke** next to "<app> (OAuth)". It stops at once. Remove it in the app too |
| Treat it like account access | Connect only apps you trust, and only to the workspace they need |

## If an app asks for a token

Some apps cannot open a sign-in page. They take a token instead.

1. **Open the Agents page.** In your Scouty dashboard, go to **Settings → Agents**.
2. **Pick your app.** Under **Set up your agent**, press your app's tile (Claude Code, Cursor, Codex, opencode, VS Code, Gemini CLI, Windsurf, or Other or REST API).
3. **Choose its permissions.** Choose what it may do and when it expires. Press **Create and copy setup**.
4. **Paste it into your agent.** Paste within **10 minutes**.
5. **Let the agent run one command.** It trades a single-use setup code for a token, saves the token to `~/.config/scouty/token` where only you can read it, and never prints it. Its config refers to `SCOUTY_TOKEN`, never the token itself.
6. **Check what it got.** The agent tells you the workspace and permissions it got.

If the app has a field for an API key rather than a terminal, press **Copy token instead**. Paste it into that field, or as the header `Authorization: Bearer <token>` if it asks for one.

> **Important:** You get the token once. Never paste it into a chat.

Where each tile puts the server, and how it refers to the token:

| Platform | Where the server goes | How to reference the secret |
|---|---|---|
| Claude Code | `.mcp.json` at the project root, `mcpServers.scouty` with `type: "http"` | `"Authorization": "Bearer ${SCOUTY_TOKEN}"` |
| Cursor | `~/.cursor/mcp.json` (or `.cursor/mcp.json`), `mcpServers.scouty` | `"Bearer ${env:SCOUTY_TOKEN}"` |
| Codex | `~/.codex/config.toml`, `[mcp_servers.scouty]` | `bearer_token_env_var = "SCOUTY_TOKEN"` |
| opencode | `opencode.json`, `mcp.scouty` with `type: "remote"` | `"Bearer {env:SCOUTY_TOKEN}"` |
| VS Code | `.vscode/mcp.json`, `servers.scouty` with `type: "http"` | `"Bearer ${env:SCOUTY_TOKEN}"` |
| Gemini CLI | `~/.gemini/settings.json`, `mcpServers.scouty` with `httpUrl` | `"Bearer ${SCOUTY_TOKEN}"` |
| Windsurf | `~/.codeium/windsurf/mcp_config.json`, `mcpServers.scouty` with `serverUrl` | `"Bearer ${env:SCOUTY_TOKEN}"` |
| Anything else | REST | `curl -H "Authorization: Bearer $SCOUTY_TOKEN" https://api.tryscouty.com/v1/me` |

## Troubleshooting

### The Scouty page says the request has expired

A sign-in request lasts **10 minutes**. Go back to the app and connect again.

### I pressed Allow and the app still says it is not connected

Close and reopen the app, then press **Connect** again. On the **Agents** page, the connection shows as "<app> (OAuth)" once it worked.

### Allow says the workspace already has 10 tokens

A workspace can hold **10** active tokens and connections. Revoke one you no longer use on the **Agents** page, then connect again.

### It worked, then stopped

One of these happened. Connect again.

- Access ran out.
- Someone revoked it.
- The person who connected it left the workspace.

### I do not see Add custom connector, or Developer mode

Some plans and workspace admins turn custom connectors off. Ask the admin of your Claude, ChatGPT, or Le Chat account, or use a developer tool instead.

### The setup command failed, or the code was already used

A setup code works **once** and lasts **10 minutes**. Press the tile on the **Agents** page again for a new one.

> **Important:** If that setup reads **Active** anyway, someone else used the code. Revoke it and press the tile again.

### The app lists no Scouty tools

- Check the address is exactly `https://api.tryscouty.com/mcp`.
- With a token, check `SCOUTY_TOKEN` was set before the app started, then restart it.
- The app only sees tools its permissions allow. To change campaigns, connect again and tick **Let it act**.