---
title: "Connect SOON to your AI tools | SOON"
description: "Plug ChatGPT, Claude, Codex, Microsoft Copilot, Cursor or your own agent into your strategic intelligence, so every conversation starts from your strategy instead of a blank page."
url: "https://soon.com.au/docs/connect"
---

SOON Platform MCP

# Connect SOON to your AI tools

Plug ChatGPT, Claude, Codex, Microsoft Copilot, Cursor or your own agent into your strategic intelligence, so every conversation starts from your strategy instead of a blank page.

Last updated 2026-09-14

## Quick connect

https://mcp.soon.com.au

Copy setup prompt gives you a message to paste straight into Claude or your AI of choice: it carries the connection details and walks you through connecting, then verifies it worked.

**Sign in**

Your SOON login + emailed one-time code

**Codex**

SOON Codex plugin

**First call**

read\_action("soon\_list\_workspaces")

Connected an MCP server before? That's everything you need. The guide below covers each tool step by step.

## What connecting gets you

SOON holds your organisation's strategic intelligence: your brain (mission, strategy, guardrails, voice) and the live research pipeline that runs against it (signals, trends, opportunities, threats, competitors, findings), organised as Account, Workspace, Project, then Research Context.

Connect your AI tools to it and:

- Every session starts **grounded in your strategy**. The agent loads your brain first, so answers reflect your positioning, not generic knowledge.
- You can pull **fresh signals, trends, opportunities and threats** for any workspace, mid-conversation.
- The agent can **propose brain updates** from what you discuss, so your strategy refines itself as you work.
- Every call is logged, so you can see who is using what and where the value lands.

The shorthand: your AI without SOON answers generically. Your AI with SOON is your organisation reasoning.

## How sign-in works

**Your AI tool is the OAuth client. SOON is the OAuth server.** That means the connection starts inside the agent, not inside SOON. There is no "Connect to Claude" button on soon.com.au; you add SOON from the tool you use.

The flow, in every tool:

1. Add a connector (or MCP server) inside the agent and paste https://mcp.soon.com.au.
2. The agent sends you to SOON's sign-in screen.
3. Enter your SOON platform email. A one-time code arrives in your inbox; enter it.
4. Approve the four access scopes (soon.account.read, soon.workspace.read, soon.portal.read, soon.portal.write). The defaults are correct.
5. You bounce back to the agent, connected.

You only see the data your SOON login can see. To revoke access later, use the workspace or account admin screens in SOON.

## Connect from Claude

1. Open Claude (claude.ai with a workspace selected, or the desktop app).
2. Click the **connector icon** in the message composer. If you can't see it, connectors aren't enabled for your workspace; ask your Claude admin.
3. Click **Add a connector**.
4. Paste https://mcp.soon.com.au and click **Add**.
5. Sign in with your soon.com.au email, enter the one-time code, and click **Authorize**.
6. Back in Claude, the connector list shows **SOON Platform MCP** with a green dot.

**Confirm it worked.** In a chat, type:

```
List the SOON workspaces I can access. Don't change anything.
```

Claude should call read\_action("soon\_list\_workspaces") with no parameters and return your accessible workspaces and their UUIDs. If an action is missing, use search\_actions and describe\_action to check the current catalogue. A missing action does not mean sign-in failed. Reconnect only if Claude reports an authentication error.

## Connect from Claude Code

Use SOON inside Claude Code to bring your workspace context into your coding sessions.

1. Add SOON from your terminal:

   ```
   claude mcp add --transport http soon https://mcp.soon.com.au
   ```
2. Open Claude Code and run /mcp. Select **soon** and authenticate through the OAuth flow. Sign in with your SOON platform email, enter the one-time code, and approve access.
3. Confirm it worked:

   ```
   read_action("soon_list_workspaces")
   ```

You should get your accessible workspaces and their UUIDs. Choose a workspace, then use describe\_action to check the inputs for soon\_get\_scope\_summary or soon\_get\_constellation and call it through read\_action with that workspace\_uuid.

## Connect from Codex

Use the SOON Codex plugin when you want SOON available inside the Codex app.

[Download the SOON Codex plugin](https://soon.com.au/downloads/soon-platform-codex-plugin.zip).

1. Open **Codex**.
2. Open **Plugins**.
3. If **SOON Platform** is already shared with your workspace, install it from the plugin directory.
4. If it is not listed yet, download the plugin above, unzip it, and add the unzipped folder as a local plugin marketplace.
5. Install **SOON Platform**.
6. When Codex asks to connect SOON, sign in with your SOON platform email, enter the one-time code, and approve access.
7. Start a new Codex thread.

Confirm it worked:

```
Use SOON to load my playbook, then list the workspaces I can see.
```

Codex should use the SOON tools and return your SOON playbook or workspace list.

The SOON plugin gives Codex the connection and the operating model together:

- soon-discover loads your playbook, account, workspaces, and live scope.
- soon-brief turns signals, trends, opportunities, threats, competitors, and findings into a decision-ready brief.
- soon-write-plan prepares safe changes with dry-runs before anything is applied.
- soon-verify-outcome checks audit events and canonical SOON state after approved writes.

For local developer setup outside the Codex app plugin, unzip the package and add the marketplace from the terminal:

```
codex plugin marketplace add /path/to/soon-platform-codex-plugin-package
```

Or configure the same MCP server directly:

```
codex mcp add soon-platform --url https://mcp.soon.com.au
codex mcp login soon-platform
```

That connects to the same SOON MCP endpoint the plugin uses: https://mcp.soon.com.au.

## Connect from Microsoft Copilot

Your team uses SOON from inside Microsoft 365 Copilot through a Copilot Studio agent. Setup happens once, by whoever manages Copilot Studio in your organisation; after that everyone uses it from Copilot or Teams.

For your IT team:

1. In **Copilot Studio**, open or create the agent that should have SOON access.
2. Go to **Tools**, then **Add a tool**, then **New tool**, then **Model Context Protocol**.
3. Server URL: https://mcp.soon.com.au. Transport: **Streamable**.
4. Authentication: **OAuth 2.0** with **dynamic discovery**. SOON supports dynamic client registration, so endpoints and credentials are discovered automatically and you don't need keys from SOON.
5. When prompted to connect, sign in with your SOON platform email and enter the one-time code from your inbox.
6. **Publish** the agent to your Microsoft 365 tenant so your team can use it from Copilot.

If your tenant policy requires a pre-registered OAuth app instead of dynamic registration, contact SOON with your redirect URI and a client ID will be issued for you.

## Connect from Cursor

Cursor configures MCP through a JSON file. Edit ~/.cursor/mcp.json:

```
{
  "mcpServers": {
    "soon-platform-mcp": {
      "url": "https://mcp.soon.com.au"
    }
  }
}
```

Restart Cursor and open the chat. Your first call to any soon\_\* tool opens the OAuth sign-in in a browser tab. From there it's the same email and one-time code flow as everywhere else.

## Connect from ChatGPT

Connect SOON in **ChatGPT on the web**, using the workspace where you want to work. You need a SOON login and permission to add custom MCP connections. Your ChatGPT plan and workspace policy determine which connections and actions are available.

If your admin has already published SOON, find **SOON Platform** in your workspace's Apps or Plugins, connect your own SOON account, then go to **Confirm your connection** below.

### Add your connection

1. Open **Settings → Security and login** and enable **Developer mode**. If your settings use **Apps**, look under **Apps → Advanced Settings** instead. If the option is unavailable, ask your workspace admin to enable custom MCP access.
2. Open [ChatGPT Plugins](https://chatgpt.com/plugins) and select **+**. In the Apps interface, use **Settings → Apps → Create**.
3. Enter these connection details:

| Field | Enter |
| --- | --- |
| Name | SOON Platform |
| Description | Use your SOON strategy and research in ChatGPT. |
| MCP server URL | https://mcp.soon.com.au |
| Authentication | OAuth |

1. Create the connection, or select **Scan Tools** if shown. When SOON sign-in opens, enter your SOON platform email and the emailed one-time code, then review and approve access.
2. Wait for the tool scan to finish. Review the available tools and select **Create** if prompted.
3. Start a **new conversation** and add SOON from the tools menu.

Use the URL exactly as shown; you do not need to add a path or paste an API key into your chat.

### Confirm your connection

Send this in your new conversation:

```
Use SOON to confirm who I'm signed in as and list the workspaces I can access. Don't change anything.
```

Check that the returned identity and workspace list match your SOON account. Then choose your workspace and ask:

```
Show the SOON scope summary for this workspace, then help me find its Brain.
```

### Connect your team

If you manage a ChatGPT Business, Enterprise or Edu workspace, create and test SOON as a draft custom app first. Confirm account access and review the available actions before publishing it from **Workspace settings → Apps → Drafts**. Set access for the people who need it, within your plan's admin controls.

Each teammate connects their own SOON account and adds SOON to a new conversation. Publishing the app does not grant additional SOON workspace access.

### If you cannot connect

- **No Developer mode or Create option:** check that you selected the intended ChatGPT workspace and ask your admin about custom MCP permissions.
- **Sign-in or tool scan fails:** check the server URL and complete SOON sign-in. If it still fails, contact SOON with the step and error message. Do not share your one-time code or tokens.
- **Connected, but no SOON tools in chat:** start a new conversation and select SOON from the tools menu.
- **Your sign-in has expired:** reconnect your SOON account from the connection settings.
- **Tools changed since setup:** refresh your developer connection, then start a new conversation. Ask your admin to review and publish updates for a shared app.

OpenAI uses both **Apps** and **Plugins** across its interfaces. Menu labels and availability can vary by account. See [OpenAI's connection guide](https://developers.openai.com/plugins/deploy/connect-chatgpt) and [workspace setup guidance](https://help.openai.com/en/articles/12584461-developer-mode-and-full-mcp-connectors-in-chatgpt) for the current steps.

**Building a Custom GPT?** GPT Actions are a separate REST integration. Use the MCP connection above for SOON in your regular ChatGPT conversations.

## Connect from a custom agent

Building your own agent on the Claude API? Point the MCP connector at SOON:

```
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();
const response = await client.beta.messages.create({
  model: "claude-opus-5",
  max_tokens: 4096,
  betas: ["mcp-client-2025-11-20"],
  mcp_servers: [
    {
      type: "url",
      url: "https://mcp.soon.com.au",
      name: "soon-platform-mcp",
      authorization_token: process.env.SOON_OAUTH_TOKEN,
    },
  ],
  tools: [{ type: "mcp_toolset", mcp_server_name: "soon-platform-mcp" }],
  messages: [
    { role: "user", content: "What changed in my SOON workspace this week?" },
  ],
});
```

For the OAuth token: complete the sign-in flow once and store the token securely, or implement the full dynamic-registration and authorization-code flow if your agent onboards new users.

## How the tools are organised

Discover the current soon\_\* actions through these tools:

| Tool | What it's for |
| --- | --- |
| search\_actions | Finds the right action for an intent, in plain language |
| describe\_action | Shows an action's inputs before you call it |
| read\_action | Runs a read action, such as soon\_list\_workspaces |
| execute\_action | Runs a write action |

Use search\_actions and describe\_action for digests, signals, opportunities, Brain search and writes. Discover what your connection supports instead of guessing action names.

## Your first five minutes

Start here after connecting to orient your agent to your data.

1. read\_action("soon\_list\_workspaces") takes no parameters and returns your accessible workspaces and their UUIDs.
2. Choose the workspace you want and note its workspace\_uuid.
3. Use describe\_action("soon\_get\_scope\_summary") to check the inputs.
4. Call read\_action("soon\_get\_scope\_summary", { workspace\_uuid }) for that workspace. You can also describe and read soon\_get\_constellation with the same workspace UUID.
5. Use search\_actions to find Brain and research actions, then describe\_action to check their inputs before calling them.

Then ask your agent about your workspace. It can discover the actions it needs as you go.

## Errors and what they mean

| Error | What's happening | Fix |
| --- | --- | --- |
| insufficient\_scope (-32003) | Your token is missing a scope | Reconnect and grant all four scopes |
| scope\_violation | A project doesn't belong to that workspace | Confirm the workspace with read\_action("soon\_list\_workspaces"), then use search\_actions("projects") to find its projects |
| validation\_error | Input doesn't match the action schema | Check describe\_action for the current inputs |
| idempotency\_replayed: true | The same write key was used twice | Not an error; the original result was returned |
| missing\_client\_uuid | Workspace setup isn't finished on SOON's side | Contact your SOON account manager |
| empty\_digest | No signals or trends in the last 7 days | A real result, not a bug; nothing to report yet |

## Safe writes: dry-run and idempotency

Every write action follows the same pattern. Build against it once and every write is safe.

1. **Dry-run** with apply: false. You get back { applied: false, dry\_run: true, result: { diff, target\_preview } }. Show the diff before committing.
2. **Apply** with apply: true and a stable idempotency\_key, derived deterministically: 
   
   ```
   idempotency_key = sha256(action + workspace_uuid + canonical_json(input))
   ```
   
    Never generate a random key per attempt; that defeats the safety net.
3. **Destructive actions** (archive\_project, archive\_research\_context) additionally require confirm: true.
4. **Retry** transient failures with the same key; the server replays the original outcome instead of writing twice.

## What the MCP does not do

Save yourself the search:

- It does **not ingest files**. To give the brain a document, use search\_actions("ingest brain source") and describe\_action to find how to register a source (a SharePoint URL, Drive ID, web page or pasted text), then use execute\_action for the write. SOON stores the reference and its extracted text; your agent reads the original through your own SharePoint or Drive connector.
- It does **not trigger research runs** from your key. Those run on SOON's schedule. Use search\_actions to find the nudge action if you want to suggest one.
- It does **not search across workspaces**. One workspace per call.
- It does **not stream**. Request and response only.
- It does **not send webhooks**.

## Prompt template for agent builders

Embedding SOON in your own agent? This system-message preamble works well:

```
You have access to the SOON Platform MCP. SOON is your user's strategic intelligence platform.

At the start of a session, call read_action("soon_list_workspaces") with no parameters. Ask which workspace to use. Describe soon_get_scope_summary or soon_get_constellation, then call it through read_action with the chosen workspace_uuid to orient.

Discover soon_* actions with search_actions(intent), then check their inputs with describe_action. Use read_action for reads and execute_action for writes instead of guessing action ids.

When the user asks "what's happening," prefer the digest actions (workspace, project and context digests) over individual entity reads. They're one round-trip and return everything grouped.

For writes (create/update/archive), always dry-run first (apply: false), show the diff, get user approval, then apply with a stable idempotency_key.

If an action returns an empty result with a "not populated" warning, do NOT retry with different limits. Report that there's no data yet.
```

## Find your next action

Use search\_actions to find what you want to do, then describe\_action to check the action's inputs. Run reads through read\_action and writes through execute\_action. Your connection's catalogue is the source of truth for available actions.

[View this page on SOON](https://soon.com.au/docs/connect)