Konfiguration

Konfigurationsoberfläche für die MCP (Model Context Protocol) Services. Die meisten Einstellungen sind für gehostete Cluster statisch (zum Deploy-Zeitpunkt über Helm-Values gesetzt); diese Seite dokumentiert, was jede einzelne bewirkt, damit Sie sie während der lokalen Entwicklung oder beim Review einer Helm-Änderung sinnvoll überschreiben können.

appsettings.json

Eine minimale Konfiguration:

{
  "DynamicTools": {
    "EnableDynamicToolGeneration": true,
    "MaxQueryResultLimit": 1000,
    "DefaultQueryLimit": 100,
    "AnalyticsTimeoutSeconds": 300,
    "EnableToolStatistics": true,
    "CkTypeGraphCacheDurationMinutes": 30,
    "PreloadModels": ["System-1.0.0", "Basic-1.0.0"]
  },
  "Runtime": {
    "MongoDB": {
      "ConnectionString": "mongodb://localhost:27017",
      "DatabaseNamePrefix": "octo_"
    }
  },
  "OctoServiceUrls": {
    "AssetServiceUrl":          "https://localhost:5001/",
    "IdentityServiceUrl":       "https://localhost:5003/",
    "CommunicationServiceUrl":  "https://localhost:5005/",
    "BotServiceUrl":            "https://localhost:5007/",
    "ReportingServiceUrl":      "https://localhost:5009/"
  }
}

DynamicTools

Einstellung	Standard	Beschreibung
`EnableDynamicToolGeneration`	`true`	Erlaubt Runtime-Entity-CRUD-Tools, gegen entdeckte CK-Typen zu arbeiten
`MaxQueryResultLimit`	`1000`	Hartes Limit für eine einzelne `query_entities` / `query_entities_simple`-Antwort
`DefaultQueryLimit`	`100`	Standard-`limit`, wenn der Aufrufer keines angibt
`AnalyticsTimeoutSeconds`	`300`	Timeout für lang laufende Aggregations-/Stream-Data-Aufrufe
`EnableToolStatistics`	`true`	Nutzungsstatistiken sammeln, die von `get_tool_statistics` bereitgestellt werden
`CkTypeGraphCacheDurationMinutes`	`30`	TTL des CK-Typ-Graph-Caches pro Tenant
`PreloadModels`	`[]`	CK-Modelle, die beim Start hydriert werden, damit der erste Aufruf die Cold-Cache-Kosten nicht zahlt

OctoServiceUrls — Backend-Endpunkte

Jede URL zeigt auf einen der OctoMesh-Backend-Services. Die Factory wirft ServiceConfigurationMissingException beim ersten Aufruf in einen nicht konfigurierten Client, sodass Sie nur die tatsächlich genutzten setzen müssen.

Einstellung	Verwendet von
`AssetServiceUrl`	Tenant-Lifecycle, Blueprints, CK Model Libraries, Models, Stream-Data-Tools
`IdentityServiceUrl`	Alle Identity-Tools (Users, Roles, Groups, Clients, Providers, API-Resources/-Scopes/-Secrets)
`CommunicationServiceUrl`	Communication-Controller-Tools (Adapter, Pipelines, Workloads, Data Flows, Trigger, Deployment Sites)
`BotServiceUrl`	File-IO-Downloads, Fixup-Skripte, Tenant-Dump/-Restore, Log-Level-Dispatch
`ReportingServiceUrl`	Reporting-Service-Tools

Umgebungsvariablen

Werte aus appsettings.json können mit Umgebungsvariablen überschrieben werden, unter Verwendung des Standard-.NET-Trennzeichens __ und eines OCTO_-Präfixes. Beispiele:

export OCTO_OCTOSERVICEURLS__ASSETSERVICEURL=https://asset.example.com/
export OCTO_OCTOSERVICEURLS__IDENTITYSERVICEURL=https://identity.example.com/
export OCTO_RUNTIME__MONGODB__CONNECTIONSTRING="mongodb://mongo.cluster.local:27017"

Gehostete Cluster verdrahten diese über Helm (values-mcp.yaml) zum Deploy-Zeitpunkt in die Umgebungsvariablen der Pods.

Tenant-Auflösung

Der Server ist in Bezug auf Tenants zustandslos. Tenants werden pro Request in dieser Prioritätsreihenfolge aufgelöst:

Tool-Parameter tenantId — explizit, von jedem tenant-bezogenen Tool akzeptiert
Route-Parameter {tenantId} — vom Legacy-Endpunkt /{tenantId}/mcp
Fehler — IsSuccess: false, ErrorMessage: "...", falls keiner von beiden vorhanden ist

Vom Server bereitgestellte Endpunkte:

Endpunkt	Beschreibung
`/mcp`	Tenantloser MCP-Endpunkt — Tenant über Tool-Parameter
`/{tenantId}/mcp`	Tenant-bezogener MCP-Endpunkt — abwärtskompatibel

Best Practice: Registrieren Sie den tenantlosen /mcp-Endpunkt einmal und übergeben Sie tenantId pro Aufruf. Eine einzelne MCP-Session kann dann in einer Konversation zwischen Tenants wechseln — genau dafür sind KI-Assistenten ausgelegt.

Authentifizierung & Session-Tokens

Der Server unterstützt zwei Authentifizierungswege (Endanwender-Flow im Tech Guide: Erste Schritte → Authentifizieren):

Interaktives OAuth (Standard für Claude Code / Claude Desktop): Der Transport ist mit .RequireAuthorization() abgesichert; ein 401 trägt WWW-Authenticate: Bearer resource_metadata=…, das auf die RFC-9728-Protected-Resource-Metadata des Servers verweist (/.well-known/oauth-protected-resource), die den Identity Service als Authorization Server bekannt gibt. Der MCP-Client registriert sich dort selbst über RFC 7591 Dynamic Client Registration (octo-dcr-*-Clients) und führt Authorization Code + PKCE im Browser aus.
Device-Flow: Das in-band-Tool authenticate treibt die OAuth2 Device Authorization mit dem Client octo-mcpServices-device an.

Implementierungsdetails:

Tokens werden pro MCP-Session gespeichert (per Mcp-Session-Id-HTTP-Header verschlüsselt) in IMcpSessionTokenStore; seit der Cross-Tenant-Unterstützung wird der Store per (sessionId, tenantId) verschlüsselt — das Login-Token ist der Home-Eintrag, ausgetauschte Zieltenant-Tokens werden daneben gecacht
Das OAuth-Access-Token wird bei jedem Aufruf an die Backend-Services weitergegeben — die Autorisierung wird dort durchgesetzt, nicht in den MCP Services
Ein Hintergrund-Service SessionTokenRefresher erneuert Access-Tokens vor Ablauf, solange ein Refresh-Token noch gültig ist
Cross-Tenant-Aufrufe: Ein Token ist an einen operierenden Tenant gebunden (tenant_id-Claim, streng durchgesetzt von TenantAuthorizationMiddleware in den Backends). Zielt ein Tool-Aufruf auf einen anderen Tenant, führt McpSessionContext.TryGetAccessTokenAsync(server, tenantId) transparent einen RFC-8693-Token-Exchange über ITenantTokenExchanger durch (Client octo-mcpServices-device, acr_values=tenant:{target}) und cacht das Ergebnis; das Tool switch_tenant tut dasselbe explizit. Die Rollen werden im Zieltenant vom Identity Service neu aufgelöst — siehe Cross-Tenant-Authentifizierung im Tech Guide
Der Bot-Service wird nicht tenant-geroutet und erhält immer das Home-/Session-Token

File-Transfers

Binäre Payloads fließen nicht durch JSON-RPC. Sie verwenden einen Out-of-band-HTTP-Kanal:

PUT /file-transfer/upload/{transferId} — der Body sind die Datei-Bytes; unterstützt Chunked Streaming
GET /file-transfer/download/{transferId} — streamt die Datei mit Content-Disposition und Range-Unterstützung

Harte Limits:

Limit	Wert
Maximale Dateigröße	5 GiB
Reservierungs-/Download-TTL	30 Minuten
Speicherort	`Path.GetTempPath()/octo-mcp-file-transfer/<random>/`

Ein Hintergrund-Service FileTransferSweeper bereinigt abgelaufene Einträge und ihre Dateien auf der Festplatte alle 5 Minuten. Transfer-IDs sind zufällige 128-Bit-GUIDs in URL-Pfaden; auf den File-Transfer-Endpunkten gibt es keine zusätzliche Auth-Prüfung. Für striktere Setups stellen Sie den Server hinter Ihr eigenes Auth-Gateway.

Never use base64-in-JSON for file content

Die File-Transfer-Endpunkte sind der einzige zugelassene Mechanismus für binäre Payloads. Das Einbetten von base64 in einen Tool-Parameter sprengt das Token-Budget des KI-Clients und den Speicher des Servers und hat keinen Fallback-Pfad.

Caching

Cache	TTL	Hinweise
CK-Typ-Graphen	30 Min (konfigurierbar)	Pro Tenant, lazy hydriert; `PreloadModels` wärmt ihn beim Start vor
Verfügbare Typen pro Tenant	An den Typ-Graph-Cache gekoppelt	Direkt nach einem Import veraltet — verifizieren Sie über `get_ck_library_status` statt `get_available_models`
Tool-Statistiken	In-Memory-Aggregation	Bereitgestellt über `get_tool_statistics`

Health & Monitoring

Endpunkt	Zweck
`/health`	Gesamt-Health des Service
`/health/ready`	Readiness-Probe
`/health/live`	Liveness-Probe

Für Laufzeit-Nutzungsstatistiken rufen Sie get_tool_statistics auf:

{ "tool": "get_tool_statistics", "parameters": { "timeRange": "day" } }

appsettings.json​

DynamicTools​

OctoServiceUrls — Backend-Endpunkte​

Umgebungsvariablen​

Tenant-Auflösung​

Authentifizierung & Session-Tokens​

File-Transfers​

Caching​

Health & Monitoring​