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.

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.

---

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.