Configuration

Configuration surface for the MCP (Model Context Protocol) Services. Most settings are static for hosted clusters (set via Helm values at deploy time); this page documents what each one does so you can override sensibly during local development or when reviewing a Helm change.

appsettings.json

A minimal configuration:

{
  "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/",
    "AdminPanelUrl":            "https://localhost:5011/"
  }
}

DynamicTools

Setting	Default	Description
EnableDynamicToolGeneration	true	Allow runtime entity CRUD tools to operate against discovered CK types
MaxQueryResultLimit	1000	Hard cap on a single query_entities / query_entities_simple response
DefaultQueryLimit	100	Default limit when the caller does not supply one
AnalyticsTimeoutSeconds	300	Timeout for long-running aggregation/stream-data calls
EnableToolStatistics	true	Collect usage statistics surfaced by get_tool_statistics
CkTypeGraphCacheDurationMinutes	30	Per-tenant CK type-graph cache TTL
PreloadModels	[]	CK models to hydrate at startup so the first call doesn't pay the cold-cache cost

OctoServiceUrls — backend endpoints

Each URL points at one of the OctoMesh backend services. The factory throws ServiceConfigurationMissingException on the first call into an unconfigured client, so you only have to set the ones you actually use.

Setting	Used by
AssetServiceUrl	Tenant lifecycle, Blueprints, CK Model Libraries, Models, Stream Data tools
IdentityServiceUrl	All Identity tools (Users, Roles, Groups, Clients, Providers, API resources/scopes/secrets)
CommunicationServiceUrl	Communication Controller tools (adapters, pipelines, workloads, data flows, triggers, pools)
BotServiceUrl	File-IO downloads, fixup scripts, tenant dump/restore, log-level dispatch
ReportingServiceUrl	Reporting service tools
AdminPanelUrl	Admin Panel log-level dispatch only

Environment variables

appsettings.json values can be overridden with environment variables using the standard .NET __ separator and an OCTO_ prefix. Examples:

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"

Hosted clusters wire these through Helm (values-mcp.yaml) into pod environment variables at deployment time.

Tenant resolution

The server is stateless with respect to tenants. Tenants are resolved per request in this priority order:

1. Tool parameter tenantId — explicit, accepted by every tenant-scoped tool
2. Route parameter {tenantId} — from the legacy /{tenantId}/mcp endpoint
3. Error — IsSuccess: false, ErrorMessage: "..." if neither is present

Endpoints exposed by the server:

Endpoint	Description
/mcp	Tenantless MCP endpoint — tenant via tool parameter
/{tenantId}/mcp	Tenant-scoped MCP endpoint — backwards compatible

Best practice: register the tenantless /mcp endpoint once and pass tenantId per call. A single MCP session can then move between tenants in one conversation, which is what AI assistants are designed to do.

Authentication & session tokens

The server uses OAuth2 Device Authorization. End-user flow is documented in the Tech Guide (Getting started → authenticate).

Implementation details:

• Tokens are stored per MCP session (keyed by the Mcp-Session-Id HTTP header) in IMcpSessionTokenStore
• The Identity Server client used for the Device Flow is octo-mcpServices-device, registered automatically on server startup
• The OAuth access token is propagated to the backend services on every call — authorisation is enforced there, not in the MCP Services
• A SessionTokenRefresher background service refreshes access tokens before expiry as long as a refresh token is still valid

File transfers

Binary payloads do not flow through JSON-RPC. They use an out-of-band HTTP channel:

• PUT /file-transfer/upload/{transferId} — body is the file bytes; supports chunked streaming
• GET /file-transfer/download/{transferId} — streams the file with Content-Disposition and range support

Hard limits:

Limit	Value
Maximum file size	5 GiB
Reservation / download TTL	30 minutes
Storage location	Path.GetTempPath()/octo-mcp-file-transfer/<random>/

A FileTransferSweeper background service purges expired entries and their on-disk files every 5 minutes. Transfer IDs are random 128-bit GUIDs in URL paths; there is no extra auth check on the file-transfer endpoints. For stricter setups, put the server behind your own auth gateway.

Never use base64-in-JSON for file content

The file-transfer endpoints are the only sanctioned mechanism for binary payloads. Embedding base64 in a tool parameter blows up the AI client's token budget and the server's memory, and has no fallback path.

Caching

Cache	TTL	Notes
CK type graphs	30 min (configurable)	Per-tenant, hydrated lazily; PreloadModels warms it at startup
Available types per tenant	Coupled to the type-graph cache	Stale right after an import — verify via get_ck_library_status instead of get_available_models
Tool statistics	In-memory aggregation	Surfaced via get_tool_statistics

Health & monitoring

Endpoint	Purpose
/health	Overall service health
/health/ready	Readiness probe
/health/live	Liveness probe

For runtime usage statistics, call get_tool_statistics:

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