MCP Server

Verbinde Claude, ChatGPT, Cursor, VS Code oder jeden beliebigen MCP-Client direkt mit deinem Workspace.

Das ist der strategische Weg, SOIS zu nutzen: bring deinen eigenen Agenten mit. Dein Sois AI Workspace ist ein vollständiger MCP-Server, sodass der KI-Agent, den du bereits verwendest, sich verbindet und direkt über deine Workspace-Tools nachdenkt. Immer mehr Menschen loggen sich überhaupt nicht mehr in die SOIS-Konsole ein. Sie sagen ihrem eigenen Claude, ChatGPT, Cursor oder Gemini, was sie brauchen, und dieser betreibt SOIS in ihrem Auftrag über MCP. Die Konsole wird zu einem Ort, um Agentenaktivitäten anzusehen und zu verwalten, nicht zum primären Ort, an dem Arbeit erledigt wird.

Jeder Client, der das Model Context Protocol spricht, kann sich verbinden und deine Workspace-Tools nutzen: Kontakte suchen, Aufgaben erstellen, E-Mails senden, Dokumente verwalten und mehr, ohne auch nur eine einzige Integration zu schreiben. Weil dein eigener Agent das Denken übernimmt, gibt SOIS keine KI in deinem Auftrag aus.

Ein Endpunkt. Standardprotokoll. Jedes Tool, das dein Account nutzen darf, steht jedem kompatiblen Client zur Verfügung.

Die eine URL

Dein Workspace stellt einen einzelnen MCP-Endpunkt bereit:

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

Der Server identifiziert sich mit deiner Workspace-Marke (zum Beispiel "Acme"), sodass er unter deinem eigenen Namen im Client erscheint. Alles Weitere hängt an dieser einen URL.

Es gibt zwei Wege zur Authentifizierung. OAuth ist der empfohlene Weg und wird von den In-App-Connectors in Claude und ChatGPT genutzt: Du fügst die URL ein, genehmigst einmal und hast kein Token, das du manuell kopieren oder rotieren müsstest. Ein Bearer-Token plus API-Key wird ebenfalls für Skripte, Server und Clients unterstützt, die kein OAuth durchführen.

Option A: OAuth 2.1 (empfohlen, nichts einzufügen)

Moderne MCP-Connectors entdecken und führen die gesamte Anmeldung für dich durch. Du gibst nur die URL an.

1. Füge in deinem Client (zum Beispiel Claude oder ChatGPT) einen benutzerdefinierten Connector hinzu und füge deine MCP-URL ein: https://<your-workspace>.sois.ai/api/mcp

2. Der Client ruft den Endpunkt ohne Token auf und erhält eine 401-Antwort mit einer Discovery-Challenge:

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

3. Der Client liest diese Metadaten, findet den Autorisierungsserver deines Workspaces, registriert sich automatisch (Dynamic Client Registration) und öffnet den Anmelde- und Zustimmungsbildschirm.

4. Du genehmigst die Verbindung in deinem SOIS-Account. Der Client erhält ein Token über PKCE (mit einem rotierenden Refresh-Token) und beginnt zu arbeiten. Es wird nie ein Token manuell kopiert.

Warum das sicher ist. Der Autorisierungsserver ist deine eigene Workspace-Domain, sodass Tokens mandantenspezifisch sind und dein Netzwerk nie verlassen. Die Autorisierung liegt bei dir: Ein gewährtes Token kann nie mehr tun, als du kannst, weil jeder Tool-Aufruf bei der Ausführung auf Berechtigungen geprüft wird. Die Scope-Strings sind absichtlich grob gehalten; die echte Grenze bilden deine nutzerbezogenen Berechtigungen.

Was der Autorisierungsserver anzeigt:

Property	Value
Authorization endpoint	`/oauth/authorize`
Token endpoint	`/oauth/token`
Registration endpoint	`/oauth/register` (Dynamic Client Registration)
Grant types	`authorization_code`, `refresh_token`
PKCE	required (`S256`)
Scopes	`mcp`, `mcp:read`, `mcp:write`, `offline_access`

Normalerweise rufst du diese nicht selbst auf; ein konformer MCP-Client durchläuft den Flow automatisch, sobald er die URL hat.

Option B: Bearer-Token + API-Key (direkt oder serverseitig)

Für Skripte, Server oder jeden Client, der kein OAuth implementiert. Du erzeugst zwei Zugangsdaten und sendest sie bei jeder Anfrage als Header.

1. Öffne Einstellungen > Deinen Agenten verbinden in deinem Sois AI Workspace.

2. Wähle deinen Client (Claude Desktop, Cursor, VS Code oder Generic) und klicke auf Zugangsdaten generieren, um ein Bearer-Token, einen API-Key und ein fertiges Konfigurationssnippet zu erhalten.

3. Füge die Konfiguration in deinen Client ein.

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

Cursor verwendet dieselbe Struktur in .cursor/mcp.json; VS Code verschachtelt sie unter "mcp": { "servers": { ... } } mit "type": "http".

Header	Value	Purpose
`Authorization`	`Bearer <token>`	Identity (Sanctum token, 90-day expiry)
`X-Api-Key`	`sois_...`	Budget and usage tracking

Zwei Zugangsdaten, weil Identität und Ausgaben getrennt sind: Ein Token weist nach, wer du bist, der Key steuert und misst Kosten, und jeder für sich ist nutzlos. (OAuth-Tokens tragen ihre Autorisierung anders, daher benötigt ein Connector bei Option A keinen X-Api-Key-Header.)

Erzeuge das Paar programmatisch, wenn du das Onboarding automatisierst:

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-Endpunkte

Ein Client kann alles, was er braucht, aus drei öffentlichen Dokumenten an der Root deines Workspaces erfahren:

Endpoint	Purpose
`/.well-known/mcp.json`	Server card: name, version, protocol version, and the OAuth metadata locations
`/.well-known/oauth-protected-resource`	RFC 9728: which authorization server protects this resource
`/.well-known/oauth-authorization-server`	RFC 8414: the authorize, token, and registration endpoints, grants, and PKCE method

Die Server Card meldet authentication.type als oauth2 und verlinkt auf die beiden OAuth-Dokumente, sodass ein Connector weiß, wie er den Flow bei Option A startet.

Protokolldetails

Der Endpunkt spricht Streamable HTTP mit JSON-RPC 2.0 (Spezifikationsversion 2025-06-18).

Sitzungslebenszyklus

Step	Request	Notes
Initialize	`POST /api/mcp` method `initialize`	Negotiates capabilities; the response carries an `Mcp-Session-Id` header
List tools	`POST /api/mcp` method `tools/list`	Returns every tool your account is allowed to use
Call a tool	`POST /api/mcp` method `tools/call`	`params.name` + `params.arguments`
Keep-alive	`GET /api/mcp` with `Mcp-Session-Id`	Opens an SSE stream for server-to-client messages
Teardown	`DELETE /api/mcp` with `Mcp-Session-Id`	Ends the session

Füge die Mcp-Session-Id aus der Initialize-Antwort in jede spätere Anfrage ein.

Unterstützte Methoden

Method	Description
`initialize`	Start a session, negotiate capabilities
`ping`	Health check
`tools/list`	List available tools with schemas
`tools/call`	Execute a tool by name with arguments
`notifications/initialized`	Client confirms initialization (no response)
`notifications/cancelled`	Client cancels a pending request (no response)

Welche Tools sind verfügbar

tools/list gibt alles zurück, was dein Account in Sois AI tun kann, gefiltert nach deinen Berechtigungen:

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)

Die genaue Liste hängt von der Rolle des authentifizierten Nutzers und den installierten Apps ab. Tools sind berechtigungsgefiltert und schließen im Fehlerfall, sodass eine Verbindung nie etwas aufrufen kann, das der Nutzer nicht nutzen darf.

Der App Builder läuft über denselben Endpunkt

Es gibt keinen separaten MCP-Server zum Erstellen von Apps. Die Extension-Builder-Tools werden als Teil desselben Workspace-MCP-Servers ausgeliefert und erscheinen in derselben tools/list, mit einer Bedingung: Sie sind admin-gated, sodass sie nur für Accounts mit Builder-Berechtigung sichtbar sind. Wenn dein Account Apps bauen kann, enthält deine Tool-Liste auch:

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

Apps zu bauen ist also dasselbe wie alles andere: Du verbindest deinen Agenten einmal mit deinem Workspace, und wenn du ein Builder bist, kann er Apps neben dem Betrieb deines Geschäfts scaffolden, validieren und veröffentlichen, alles über den einen /api/mcp-Endpunkt. Siehe Build an app für den Workflow.

(Nicht zu verwechseln mit dem öffentlichen, nur lesbaren Build-Context-Connector, den ein Operator hinzufügen kann, um die Fähigkeiten eines Netzwerks zu bewerben; das ist ein separater, nicht authentifizierter Endpunkt auf der Netzwerkdomain, nicht dein Workspace-MCP-Server.)

Budget, Limits und Fehler

What	Value
Rate limit	120 requests/minute
Tool-call cost	metered as AI credits
Budget	per API key (Option B) or per workspace; you set the cap
Token expiry	90 days (Option B Sanctum token); OAuth tokens refresh automatically

Standard-JSON-RPC-Fehler gelten, plus ein paar spezifische Codes:

Code	Meaning
`-32001`	Unauthorized or session expired (Option A connectors get the OAuth challenge here)
`-32002`	Insufficient AI credits
`-32003`	Tool not permitted for this account
`-32004`	Budget cap reached

Teste deine Verbindung

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

Gibt zurück, ob die Zugangsdaten funktionieren und wie viele Tools für sie sichtbar sind.

Deinen eigenen Agenten mitzubringen ist der strategische Weg. Der MCP Server lässt deinen eigenen KI-Client direkt über deine SOIS-Tools nachdenken, sodass SOIS keine KI in deinem Auftrag ausgibt. Das Chat Agent Gateway ist der Einstieg für Aufrufer, die keinen Agenten haben: Klartext-Nachrichten über HTTP, bei denen SOISs eigener Agent das Denken übernimmt. Nutze, was zu deinem Aufrufer passt, oder beides.

Möchtest du Sois stattdessen mit externen MCP-Servern verbinden? Siehe das MCP Gateway für ausgehende Verbindungen.