> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trysoar.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect

> One URL, an OAuth sign-in, and the scopes to grant

The endpoint is:

```text theme={null}
https://mcp.trysoar.com/mcp
```

You never enter an API key, and you never paste a client id or secret. Your client
registers itself, you sign in to SOAR, and SOAR issues it a token scoped to what you
approved.

<Tip>
  Testing? Point at `https://mcp.staging.trysoar.com/mcp` instead. Accounts, keys and
  grants are per-environment, so a staging connection touches nothing in production.
</Tip>

## Start with reads

Grant the two read scopes first and add write access once you trust the setup. The
server **omits every write tool** from its tool list until your token carries a write
scope, so a read-only grant is enforced, not merely advisory.

```text theme={null}
soar:markets:read soar:account:read
```

When you want to place orders, re-authenticate with all four:

```text theme={null}
soar:markets:read soar:account:read soar:orders:write soar:orders:bulk-cancel
```

| Scope | Grants |
| - | - |
| `soar:markets:read` | The market catalog, ladders, books, candles, and trades |
| `soar:account:read` | Your orders, fills, balances, positions, and personalized reads |
| `soar:orders:write` | Placing, amending, and canceling one known order |
| `soar:orders:bulk-cancel` | Canceling every resting order in a market or event |

## Claude, Claude Desktop, and mobile

Open **Customize → Connectors → Add custom connector**, enter the URL, leave the
advanced OAuth fields empty, then select **Connect** and sign in.

Claude requests the scope set the server advertises, so read the consent screen before
approving.

<Note>
  On Team and Enterprise plans an Owner or Primary Owner adds the connector under
  **Organization settings → Connectors** before members can connect individually. Set
  each write tool to **Needs approval**, or **Blocked** for a read-only rollout, under
  **Tool permissions**.
</Note>

## Claude Code

Add the server with the read scopes pinned, then complete OAuth:

```bash theme={null}
claude mcp add-json --scope user soar \
  '{"type":"http","url":"https://mcp.trysoar.com/mcp","oauth":{"scopes":"soar:markets:read soar:account:read"}}'
```

```bash theme={null}
claude mcp login soar
```

Verify with `claude mcp get soar`. Claude Code presents its own published client
identity, so there is nothing to configure beyond the URL.

## ChatGPT and Codex

Codex discovers the endpoint from its protected-resource metadata — configure the
server URL and leave the OAuth resource unset. The public SOAR client for Codex uses
PKCE and has no secret. Then:

```bash theme={null}
codex mcp login soar
```

Codex uses a fixed loopback callback port so the registered redirect stays
deterministic. If you change scopes, run `codex mcp logout soar` and log in again —
an existing token keeps the scopes it was issued with.

## Approval

Two independent layers stand between a suggestion and a filled order, and neither
replaces the other.

1. **Scope.** A tool the token has no scope for is not in the list at all. Nothing to
   approve, nothing to call.
2. **Your client.** Every write, and every account-sensitive read, is flagged so the
   client asks a person before the call — even where a permissive setting would
   otherwise skip the prompt.

<Warning>
  An assistant deciding what to trade is not the same as you deciding. Grant write
  scopes only when you intend the assistant to move your positions, and keep the
  per-call prompt on. `soar_cancel_market_orders` in particular fans out across an
  entire market or event.
</Warning>

## When something fails

| What you see | What it means |
| - | - |
| A write tool is missing from the list | Your token has no write scope. Re-authenticate with the fuller set. |
| `disposition: "auth"` | The token lacks the scope named in the error. Log out, log in again. |
| `disposition: "retry_idempotent_only"` | The write may have committed. Ask for the order to be polled, not re-sent with a new id. |
| Nothing connects at all | Check the URL is the `/mcp` path exactly, and that an org Owner has approved the connector if you are on Team or Enterprise. |

The full error vocabulary behind these dispositions is the REST one:
[Errors](/api-reference/errors).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.