MCP Server

Connect Claude, ChatGPT, Cursor, VS Code, or any MCP client directly to your workspace.

---

This is the strategic way to use Sois: bring your own agent. Your Sois AI workspace is a full MCP server, so the AI agent you already use connects and reasons over your workspace tools directly. Increasingly, people never log into the Sois console at all. They tell their own Claude, ChatGPT, Cursor or Gemini what they need, and it operates Sois on their behalf over MCP. The console becomes a place to view and manage agent activity, not the primary way work gets done.

Any client that speaks the Model Context Protocol can connect and use your workspace tools: search contacts, create tasks, send emails, manage documents, and more, without writing a single integration. Because your own agent does the reasoning, Sois spends no AI on your behalf.

One endpoint. Standard protocol. Every tool your account is allowed to use, available to any compatible client.

---

The one URL

Your workspace exposes a single MCP endpoint:

https://<your-workspace>.sois.ai/api/mcp

The server identifies itself with your workspace brand (for example "Acme"), so it shows up under your own name in the client. Everything below hangs off that one URL.

There are two ways to authenticate. OAuth is the recommended path and is what the in-app connectors in Claude and ChatGPT use: you paste the URL, approve once, and there is no token to copy or rotate by hand. A Bearer token plus API key is also supported for scripts, servers, and clients that do not do OAuth.

---

Option A: OAuth 2.1 (recommended, nothing to paste)

Modern MCP connectors discover and complete the whole sign-in for you. You only provide the URL.

1. In your client (for example Claude or ChatGPT), add a custom connector and paste your MCP URL: https://<your-workspace>.sois.ai/api/mcp

2. The client calls the endpoint with no token and receives a 401 carrying a discovery challenge:

WWW-Authenticate: Bearer resource_metadata="https://<your-workspace>.sois.ai/.well-known/oauth-protected-resource"

3. The client reads that metadata, finds your workspace's authorization server, registers itself automatically (Dynamic Client Registration), and opens the sign-in and consent screen.

4. You approve the connection in your Sois account. The client receives a token over PKCE (with a rotating refresh token) and starts working. No token is ever copied by hand.

Why this is safe. The authorization server is your own workspace domain, so tokens are tenant-scoped and never leave your network. Authorization is your role: a granted token can never do more than you can, because every tool call is permission-checked at execution. The scope strings are coarse on purpose; the real boundary is your per-user permissions.

What the authorization server advertises:

You do not normally call these yourself; a compliant MCP client walks the flow automatically once it has the URL.

---

Option B: Bearer token + API key (direct or server-side)

For scripts, servers, or any client that does not implement OAuth. You generate two credentials and send them as headers on every request.

1. Open Settings > Connect your Agent in your Sois AI workspace.

2. Choose your client (Claude Desktop, Cursor, VS Code, or Generic) and click Generate Credentials to get a Bearer token, an API key, and a ready-made config snippet.

3. Paste the config into your client.

{
  "mcpServers": {
    "sois-workspace": {
      "url": "https://<your-workspace>.sois.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN",
        "X-Api-Key": "YOUR_API_KEY"
      }
    }
  }
}

Cursor uses the same shape in .cursor/mcp.json; VS Code nests it under "mcp": { "servers": { ... } } with "type": "http".

Two credentials because identity and spend are separate: a token proves who you are, the key controls and meters cost, and either one alone is useless. (OAuth tokens carry their authorization differently, so a connector on Option A does not need the X-Api-Key header.)

Generate the pair programmatically when you are automating onboarding:

curl -X POST "https://<your-workspace>.sois.ai/api/mcp/quick-setup" \
  -H "Authorization: Bearer YOUR_EXISTING_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"client": "generic"}'

---

Discovery endpoints

A client can learn everything it needs from three public documents at your workspace root:

The server card reports authentication.type as oauth2 and links to the two OAuth documents, which is how a connector knows to start the flow in Option A.

---

Protocol details

The endpoint speaks Streamable HTTP with JSON-RPC 2.0 (spec version 2025-06-18).

Session lifecycle

Include the Mcp-Session-Id from the initialize response on every later request.

Supported methods

---

What tools are available

tools/list returns everything your account can do inside Sois AI, filtered to your permissions:

• Contacts: search, create, update, summarise
• Tasks: create, assign, update status, search
• Calendar: list, create, update events, check availability
• Documents: search, create, update content
• Files: browse, upload, download
• Inbox: read, compose, send
• Departments and team: list and manage (admin)
• Installed apps: every tool added by the extensions you have installed (CRM, invoicing, warehouse, custom entities, and so on)

The exact list depends on the authenticated user's role and installed apps. Tools are permission-filtered and fail closed, so a connection can never call something the user is not allowed to use.

Full tool reference

Generated from the live tool definitions, so it never drifts from what tools/list returns. 622 tools across 47 areas. Your own connection shows a subset: tools are filtered by your role and by which apps you have installed.

Apps built for a single customer add their own tools. Those are documented inside that workspace, on Settings → Connect your Agent, not here.

Accounting (44)

Agent Web Browser (2)

Listeners (12)

Tasks (33)

Teams (9)

Blog (17)

Agent Browser Tab (5)

Calendars (8)

Contacts (25)

Customer Service (7)

Deals Pipeline (29)

Departments (10)

Agent Dialer (7)

Documents (8)

Events (19)

Expedia (11)

Extension Builder (15)

Files (15)

Flights and Stays (8)

Form Builder (18)

Google Meet (1)

Group Accounts (14)

HR (40)

Email Inbox (12)

Marketing (46)

MCP Gateway (5)

Notifications (9)

Credential Vaults (2)

People Tracker (1)

Personal Assistant (11)

Platform (58)

Reports (5)

Signatures (10)

Slack (8)

Team Members (7)

Microsoft Teams (1)

Todo Lists (8)

Destinations (3)

Flights (3)

Hotels (3)

Travel Planner (20)

Transfers (3)

Trips (3)

Client Users (1)

Warehouse (42)

WhatsApp Messaging (3)

Zoom (1)

The app builder runs over this same endpoint

There is no separate MCP server for building apps. The extension-builder tools ship as part of the same workspace MCP server and appear in the same tools/list, with one condition: they are admin-gated, so they surface only for builder-capable accounts. If your account can build apps, your tool list also includes:

• getExtensionRules, getExtensionFrameSpec (what an app must look like)
• createExtensionProject, listExtensionProjects, getExtensionStatus
• validateExtensionBundle, uploadExtensionBundle

So building an app is the same act as everything else: you connect your agent to your workspace once, and if you are a builder it can scaffold, validate, and publish an app alongside running your business, all through the one /api/mcp endpoint. See Build an app for the workflow.

(Not to be confused with the public, read-only build-context connector an operator can add to advertise a network's capabilities; that is a separate, unauthenticated endpoint on the network domain, not your workspace MCP server.)

---

Budget, limits, and errors

Standard JSON-RPC errors apply, plus a few specific codes:

---

Test your connection

curl -X POST "https://<your-workspace>.sois.ai/api/mcp/test" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Api-Key: YOUR_API_KEY"

Returns whether the credentials work and how many tools are visible to them.

---

Per-client setup

Connecting Sois is identical at the protocol level (paste your MCP URL → OAuth or Bearer auth) but each client has its own config file and reload procedure. Pick yours:

Claude Desktop

1. Open Claude Desktop → Settings → Developer → Edit Config (or open ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows, ~/.config/Claude/claude_desktop_config.json on Linux).
2. Add an mcpServers entry pointing at your workspace MCP URL with the mcp-remote stdio bridge (or use the in-app Add custom connector flow if your Claude Desktop version exposes it — that path uses OAuth and skips the JSON file entirely).
3. Quit Claude Desktop completely (⌘Q on macOS, Alt+F4 on Windows) and reopen it.
4. Open the plug menu in any chat. Your workspace should appear in the list.

ChatGPT

1. ChatGPT Desktop → Settings → Apps → Advanced settings → Create app.
2. Turn on Developer mode (acknowledge the warning), then click Create app.
3. Name it "Sois", set Connection to Server URL, paste your MCP URL.
4. For Authentication, choose OAuth. ChatGPT discovers the Sois OAuth endpoints automatically and walks you through the sign-in + consent flow on first use.

Cursor

1. Create or open ~/.cursor/mcp.json (or .cursor/mcp.json in a repo root for project scope).
2. Add an mcpServers entry with your workspace MCP URL + bearer headers.
3. Restart Cursor. Sois should appear in the MCP panel.

VS Code Copilot Chat

1. Open the command palette → Preferences: Open User Settings (JSON).
2. Add a top-level mcp block with your workspace URL + headers.
3. Reload the window. Sois tools appear in the Copilot tray.

Other MCP-capable clients

Any client that supports remote MCP over HTTP with a bearer token can connect. Use the URL + headers from your workspace's Connect your agent view and follow the client's "Add remote MCP server" docs.

---

Enable autonomous bundle uploads (Claude Desktop)

When you want your agent to push a finished extension bundle to Sois itself (rather than uploading via the dev console's drop-zone), the agent's bash / code-execution sandbox must be allowed to reach the Sois host. Claude Desktop is the only client today that has a per-app domain allowlist sitting in front of the bash tool — and by default it does not include user domains.

To enable autonomous uploads from a Claude Desktop agent:

1. Claude Desktop → Settings → Capabilities.

2. Under Code execution and file creation, enable both Cloud code execution and file creation and Allow network egress.

3. Domain allowlist → choose Custom (or Package managers only with additional allowed domains).

4. Add these production hosts under Additional allowed domains (paste each, click Add):

   *.sois.ai
   app.sois.ai
   sois.ai
   

5. Quit and reopen Claude Desktop. Your agent's bash / curl can now reach Sois.

Without this allowlist, the agent's PUT to the presigned-upload URL will fail with a host-not-allowed / DNS error, and uploads will silently hang or never leave the client.

Cursor / VS Code Copilot / ChatGPT do not need this — Cursor's agent uses your local shell directly (no per-app sandbox), and ChatGPT custom connectors route network calls through the OAuth-bound MCP transport, not a separate sandbox. Autonomous uploads from those clients work without additional setup.

---

Bringing your own agent is the strategic path. The MCP Server lets your own AI client reason over your Sois tools directly, so Sois spends no AI on your behalf. The Chat Agent Gateway is the on-ramp for callers that have no agent: plain-English messages over HTTP, where Sois's own agent does the reasoning. Use whichever fits your caller, or both.

---

Want to connect Sois to external MCP servers instead? See the MCP Gateway for outbound connections.