Connect SOON to your AI tools

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.

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 and select +. In the Apps interface, use Settings → Apps → Create.
3. Enter these connection details:

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 and workspace setup guidance 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:

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

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.