Core Concepts

How Conductor works

The architecture behind the tool call pipeline, plugin system, and security model.

Architecture

Conductor sits between your AI client and the real world. The AI client speaks the MCP protocol — Conductor translates those tool calls into real operations (file reads, shell commands, database queries) and sends back results.

architecture

┌─────────────────────────────────────────────────┐
│               AI Client (Claude Code)            │
│   "read src/index.ts"  →  calls filesystem.read  │
└───────────────────────┬─────────────────────────┘
                        │ MCP protocol (stdio / HTTP)
                        ▼
┌─────────────────────────────────────────────────┐
│                  Conductor                       │
│                                                  │
│  ┌──────────┐  ┌──────────┐  ┌──────────────┐   │
│  │ Validate │→ │ Approve? │→ │ Circuit chk  │   │
│  └──────────┘  └──────────┘  └──────┬───────┘   │
│                                     │            │
│  ┌──────────────────────────────────▼──────────┐ │
│  │           Plugin handler runs               │ │
│  └──────────────────────────────────┬──────────┘ │
│                                     │            │
│  ┌──────────────────────────────────▼──────────┐ │
│  │    Audit log (SHA-256 chained)              │ │
│  └─────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────┘
                        │
          ┌─────────────┼──────────────┐
          ▼             ▼              ▼
     Filesystem      Shell        Database

Tool call lifecycle

Every single tool call — regardless of plugin — goes through this exact sequence:

AI sends tool call

The AI client sends a JSON-RPC `tools/call` request over the transport. This is the MCP wire format — Conductor is transport-agnostic.

Input validation

The input is validated against the tool's `inputSchema` (JSON Schema). Invalid inputs are rejected before any code runs.

Approval gate

If `requiresApproval: true`, execution pauses. Conductor writes a prompt to stderr and waits for the user to type 'y' or 'n'. The AI waits.

Circuit breaker check

If the circuit is OPEN (too many recent failures), the call returns an error immediately. No handler is invoked. The AI is informed.

Handler runs

The plugin's async handler executes. If it throws, Conductor retries with exponential backoff (configurable). Failures update the circuit breaker.

Audit log write

The call, input hash, result, duration, and SHA-256 chain link are appended to ~/.conductor/audit.log. This step cannot be skipped.

Response returned

The result is sent back to the AI client as a `CallToolResult`. The AI continues its task.

Plugin model

A plugin is a JavaScript module that exports a Plugin object. Conductor discovers and loads plugins at startup. Each plugin registers one or more tools, each with a typed input schema and a handler function.

plugin interface

interface Plugin {
  name: string;            // unique identifier
  version: string;         // semver
  description: string;

  // JSON Schema — validated before handler runs
  configSchema?: JSONSchema;

  tools: ToolDefinition[];
}

interface ToolDefinition {
  name: string;            // e.g. "filesystem.read"
  description: string;     // shown to AI
  inputSchema: JSONSchema; // validated on every call
  requiresApproval?: boolean;

  handler(input: unknown, config: unknown): Promise<CallToolResult>;
}

Transport layer

Conductor supports two transport modes. The transport determines how the AI client communicates with Conductor — it has no effect on which tools are available or how they behave.

stdio (default)

When to use: Local AI clients: Claude Desktop, Claude Code, Cursor, Cline, Windsurf

The AI client spawns a `conductor mcp start` process and talks to it over stdin/stdout. Lifecycle is managed by the client.

conductor mcp start

HTTP

When to use: Remote access, shared team servers, CI/CD, webhooks

Conductor binds to a port and exposes an HTTP/SSE endpoint. Multiple clients can connect simultaneously.

conductor mcp start --transport http --port 3000

Transport reference

Security layers

Input validation

JSON Schema enforced before every handler call. No handler runs with invalid input.

Allowlisting

Shell plugin restricts to an explicit command list. No eval, no wildcards, no exceptions.

Approval gates

Destructive operations pause for user confirmation. The AI cannot bypass this.

Circuit breakers

Per-tool failure counters. After threshold, circuit opens. Fail-fast, no cascades.

Encrypted secrets

AES-256-GCM, key in OS keychain. Secrets never appear in config files or logs.

Audit chain

SHA-256 linked append-only log. Every call recorded. Tampering is mathematically detectable.

Full security model

Next: Configuration