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.
Open the Agents page
In your Scouty dashboard, go to Settings → Agents.
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).
Choose its permissions
Choose what it may do and when it expires. Press Create and copy setup.
Paste it into your agent
Paste within 10 minutes.
Let the agent run one command
It trades a single-use setup code for a token, saves the token to
~/.config/scouty/tokenwhere only you can read it, and never prints it. Its config refers toSCOUTY_TOKEN, never the token itself.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_TOKENwas 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.