Skip to main content

Services and Integrations

This page covers the non-core modules that connect Caracal to external execution surfaces and operational tooling.

Audience: Developer

Context: Use this page when working on the HTTP service, provider integrations, monitoring surfaces, or deployment helpers.

Core Explanation​

MCP service and adapter​

The MCP path has two layers:

  • caracal/mcp/adapter.py performs authority interception and metering around tool calls and resource reads
  • caracal/mcp/service.py exposes the HTTP service that receives those requests, reports health, and forwards to configured MCP servers

The adapter is where mandate lookup and validation meet the integration surface.

Provider catalog and workspace registry​

Provider handling is split between:

  • static scope grammar and provider-definition helpers in caracal/provider/definitions.py
  • catalog and record-construction helpers in caracal/provider/catalog.py
  • workspace provider registry helpers in caracal/provider/workspace.py

This split lets the runtime validate policy and mandate scopes against concrete provider definitions stored per workspace.

Monitoring​

Monitoring is spread across:

  • caracal/monitoring/health.py
  • caracal/monitoring/metrics.py
  • caracal/monitoring/http_server.py

The project exposes both structured health checks and Prometheus-oriented metrics surfaces.

Deployment helpers​

caracal/deployment contains:

  • mode and edition management
  • workspace config manager
  • sync state
  • migration helpers
  • gateway and broker-related client or helper modules

This package is where operational configuration and cross-environment behavior is centralized.

Internal Behavior​

Notable cross-module rules:

  • MCP requests are denied when mandate validation cannot succeed
  • provider add and scope validation flows are workspace-sensitive
  • monitoring modules rely on runtime services and backend health, not just process liveness
  • deployment commands often bridge filesystem state, workspace metadata, secret storage, and PostgreSQL schema operations

Public Enterprise Boundary​

This layer is also where public enterprise-adjacent behavior becomes visible:

  • sync metadata and commands
  • edition and gateway awareness
  • provider restrictions in enterprise gateway mode
  • public remote URL storage

The open-source docs stop at that boundary.

Edge Cases And Constraints​

  • The MCP service and monitoring surfaces are part of the runtime, but they are not interchangeable. One enforces execution paths; the other reports operational state.
  • Provider definitions are not optional decoration. They feed into scope validation used by authority and policy code.
  • Some deployment modules reflect future or connector behavior that is broader than the currently documented open-source workflows.
AI tools
On this page