@vellumai/assistant 0.3.20 → 0.3.22

package/src/__tests__/mcp-cli.test.ts

@@ -0,0 +1,141 @@
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from 'bun:test';
+
+const CLI = join(import.meta.dir, '..', 'index.ts');
+
+let testDataDir: string;
+let configPath: string;
+
+function runMcpList(args: string[] = []): { stdout: string; exitCode: number } {
+  const result = spawnSync('bun', ['run', CLI, 'mcp', 'list', ...args], {
+    encoding: 'utf-8',
+    timeout: 10_000,
+    env: { ...process.env, BASE_DATA_DIR: testDataDir },
+  });
+  return {
+    stdout: (result.stdout ?? '').toString(),
+    exitCode: result.status ?? 1,
+  };
+}
+
+function writeConfig(config: Record<string, unknown>): void {
+  writeFileSync(configPath, JSON.stringify(config), 'utf-8');
+}
+
+describe('vellum mcp list', () => {
+  beforeAll(() => {
+    testDataDir = join(tmpdir(), `vellum-mcp-cli-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    const workspaceDir = join(testDataDir, '.vellum', 'workspace');
+    mkdirSync(workspaceDir, { recursive: true });
+    configPath = join(workspaceDir, 'config.json');
+    writeConfig({});
+  });
+
+  afterAll(() => {
+    rmSync(testDataDir, { recursive: true, force: true });
+  });
+
+  beforeEach(() => {
+    writeConfig({});
+  });
+
+  test('shows message when no MCP servers configured', () => {
+    const { stdout, exitCode } = runMcpList();
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain('No MCP servers configured');
+  });
+
+  test('lists configured servers', () => {
+    writeConfig({
+      mcp: {
+        servers: {
+          'test-server': {
+            transport: { type: 'streamable-http', url: 'https://example.com/mcp' },
+            enabled: true,
+            defaultRiskLevel: 'medium',
+          },
+        },
+      },
+    });
+
+    const { stdout, exitCode } = runMcpList();
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain('1 MCP server(s) configured');
+    expect(stdout).toContain('test-server');
+    expect(stdout).toContain('streamable-http');
+    expect(stdout).toContain('https://example.com/mcp');
+    expect(stdout).toContain('medium');
+  });
+
+  test('shows disabled status', () => {
+    writeConfig({
+      mcp: {
+        servers: {
+          'disabled-server': {
+            transport: { type: 'sse', url: 'https://example.com/sse' },
+            enabled: false,
+            defaultRiskLevel: 'high',
+          },
+        },
+      },
+    });
+
+    const { stdout, exitCode } = runMcpList();
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain('disabled');
+  });
+
+  test('shows stdio command info', () => {
+    writeConfig({
+      mcp: {
+        servers: {
+          'stdio-server': {
+            transport: { type: 'stdio', command: 'npx', args: ['-y', 'some-mcp-server'] },
+            enabled: true,
+            defaultRiskLevel: 'low',
+          },
+        },
+      },
+    });
+
+    const { stdout, exitCode } = runMcpList();
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain('stdio-server');
+    expect(stdout).toContain('stdio');
+    expect(stdout).toContain('npx -y some-mcp-server');
+    expect(stdout).toContain('low');
+  });
+
+  test('--json outputs valid JSON', () => {
+    writeConfig({
+      mcp: {
+        servers: {
+          'json-server': {
+            transport: { type: 'streamable-http', url: 'https://example.com/mcp' },
+            enabled: true,
+            defaultRiskLevel: 'high',
+          },
+        },
+      },
+    });
+
+    const { stdout, exitCode } = runMcpList(['--json']);
+    expect(exitCode).toBe(0);
+    const parsed = JSON.parse(stdout);
+    expect(Array.isArray(parsed)).toBe(true);
+    expect(parsed).toHaveLength(1);
+    expect(parsed[0].id).toBe('json-server');
+    expect(parsed[0].transport.url).toBe('https://example.com/mcp');
+  });
+
+  test('--json outputs empty array when no servers', () => {
+    const { stdout, exitCode } = runMcpList(['--json']);
+    expect(exitCode).toBe(0);
+    const parsed = JSON.parse(stdout);
+    expect(parsed).toEqual([]);
+  });
+});

package/src/cli/mcp.ts

@@ -0,0 +1,130 @@
+import type { Command } from 'commander';
+
+import { loadRawConfig, saveRawConfig } from '../config/loader.js';
+import type { McpConfig, McpServerConfig } from '../config/mcp-schema.js';
+import { getCliLogger } from '../util/logger.js';
+
+const log = getCliLogger('cli');
+
+export function registerMcpCommand(program: Command): void {
+  const mcp = program.command('mcp').description('Manage MCP (Model Context Protocol) servers');
+
+  mcp
+    .command('list')
+    .description('List configured MCP servers and their status')
+    .option('--json', 'Output as JSON')
+    .action((opts: { json?: boolean }) => {
+      const raw = loadRawConfig();
+      const mcpConfig = raw.mcp as Partial<McpConfig> | undefined;
+      const servers = mcpConfig?.servers ?? {};
+      const entries = Object.entries(servers) as [string, McpServerConfig][];
+
+      if (entries.length === 0) {
+        if (opts.json) {
+          process.stdout.write(JSON.stringify([], null, 2) + '\n');
+        } else {
+          log.info('No MCP servers configured.');
+        }
+        return;
+      }
+
+      if (opts.json) {
+        const result = entries
+          .filter(([, config]) => config && typeof config === 'object')
+          .map(([id, config]) => ({ id, ...config }));
+        process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+        return;
+      }
+
+      log.info(`${entries.length} MCP server(s) configured:\n`);
+      for (const [id, cfg] of entries) {
+        if (!cfg || typeof cfg !== 'object') {
+          log.info(`  ${id} (invalid config — skipped)\n`);
+          continue;
+        }
+        const enabled = cfg.enabled !== false;
+        const transport = cfg.transport;
+        const risk = cfg.defaultRiskLevel ?? 'high';
+        const status = enabled ? '✓ enabled' : '✗ disabled';
+
+        log.info(`  ${id}`);
+        log.info(`    Status:    ${status}`);
+        log.info(`    Transport: ${transport?.type ?? 'unknown'}`);
+        if (transport?.type === 'stdio') {
+          log.info(`    Command:   ${transport.command} ${(transport.args ?? []).join(' ')}`);
+        } else if (transport && 'url' in transport) {
+          log.info(`    URL:       ${transport.url}`);
+        }
+        log.info(`    Risk:      ${risk}`);
+        if (cfg.allowedTools) log.info(`    Allowed:   ${cfg.allowedTools.join(', ')}`);
+        if (cfg.blockedTools) log.info(`    Blocked:   ${cfg.blockedTools.join(', ')}`);
+        log.info('');
+      }
+    });
+
+  mcp
+    .command('add <name>')
+    .description('Add an MCP server configuration')
+    .requiredOption('-t, --transport-type <type>', 'Transport type: stdio, sse, or streamable-http')
+    .option('-u, --url <url>', 'Server URL (for sse/streamable-http)')
+    .option('-c, --command <cmd>', 'Command to run (for stdio)')
+    .option('-a, --args <args...>', 'Command arguments (for stdio)')
+    .option('-r, --risk <level>', 'Default risk level: low, medium, or high', 'high')
+    .option('--disabled', 'Add as disabled')
+    .action((name: string, opts: {
+      transportType: string;
+      url?: string;
+      command?: string;
+      args?: string[];
+      risk: string;
+      disabled?: boolean;
+    }) => {
+      const raw = loadRawConfig();
+      if (!raw.mcp) raw.mcp = { servers: {} };
+      const mcpConfig = raw.mcp as Record<string, unknown>;
+      if (!mcpConfig.servers) mcpConfig.servers = {};
+      const servers = mcpConfig.servers as Record<string, unknown>;
+
+      if (servers[name]) {
+        log.error(`MCP server "${name}" already exists. Remove it first with: vellum mcp remove ${name}`);
+        return;
+      }
+
+      let transport: Record<string, unknown>;
+      switch (opts.transportType) {
+        case 'stdio':
+          if (!opts.command) {
+            log.error('--command is required for stdio transport');
+            return;
+          }
+          transport = { type: 'stdio', command: opts.command, args: opts.args ?? [] };
+          break;
+        case 'sse':
+        case 'streamable-http':
+          if (!opts.url) {
+            log.error(`--url is required for ${opts.transportType} transport`);
+            return;
+          }
+          transport = { type: opts.transportType, url: opts.url };
+          break;
+        default:
+          log.error(`Unknown transport type: ${opts.transportType}. Must be stdio, sse, or streamable-http`);
+          return;
+      }
+
+      if (!['low', 'medium', 'high'].includes(opts.risk)) {
+        log.error(`Invalid risk level: ${opts.risk}. Must be low, medium, or high`);
+        return;
+      }
+
+      servers[name] = {
+        transport,
+        enabled: !opts.disabled,
+        defaultRiskLevel: opts.risk,
+      };
+
+      saveRawConfig(raw);
+      log.info(`Added MCP server "${name}" (${opts.transportType})`);
+      log.info('Restart the daemon for changes to take effect: vellum daemon restart');
+    });
+}

package/src/config/mcp-schema.ts

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+
+const McpStdioTransportSchema = z.object({
+  type: z.literal('stdio'),
+  command: z.string({ error: 'mcp transport command must be a string' }),
+  args: z.array(z.string()).default([]),
+  env: z.record(z.string(), z.string()).optional(),
+});
+
+const McpSseTransportSchema = z.object({
+  type: z.literal('sse'),
+  url: z.string({ error: 'mcp transport url must be a string' }),
+  headers: z.record(z.string(), z.string()).optional(),
+});
+
+const McpStreamableHttpTransportSchema = z.object({
+  type: z.literal('streamable-http'),
+  url: z.string({ error: 'mcp transport url must be a string' }),
+  headers: z.record(z.string(), z.string()).optional(),
+});
+
+export const McpTransportSchema = z.discriminatedUnion('type', [
+  McpStdioTransportSchema,
+  McpSseTransportSchema,
+  McpStreamableHttpTransportSchema,
+]);
+
+export const McpServerConfigSchema = z.object({
+  transport: McpTransportSchema,
+  enabled: z.boolean({ error: 'mcp server enabled must be a boolean' }).default(true),
+  defaultRiskLevel: z.enum(['low', 'medium', 'high'], {
+    error: 'mcp server defaultRiskLevel must be one of: low, medium, high',
+  }).default('high'),
+  maxTools: z.number({ error: 'mcp server maxTools must be a number' }).int().positive().default(20),
+  allowedTools: z.array(z.string()).optional(),
+  blockedTools: z.array(z.string()).optional(),
+});
+
+export const McpConfigSchema = z.object({
+  servers: z.record(z.string(), McpServerConfigSchema).default({} as any),
+  globalMaxTools: z.number({ error: 'mcp globalMaxTools must be a number' }).int().positive().default(50),
+});
+
+export type McpTransport = z.infer<typeof McpTransportSchema>;
+export type McpServerConfig = z.infer<typeof McpServerConfigSchema>;
+export type McpConfig = z.infer<typeof McpConfigSchema>;

package/src/config/schema.ts

@@ -114,6 +114,16 @@ export type {
 export {
   SandboxConfigSchema,
 } from './sandbox-schema.js';
+export type {
+  McpConfig,
+  McpServerConfig,
+  McpTransport,
+} from './mcp-schema.js';
+export {
+  McpConfigSchema,
+  McpServerConfigSchema,
+  McpTransportSchema,
+} from './mcp-schema.js';
 export type {
   RemotePolicyConfig,
   RemoteProviderConfig,
@@ -152,6 +162,7 @@ import {
   TimeoutConfigSchema,
   UiConfigSchema,
 } from './core-schema.js';
+import { McpConfigSchema } from './mcp-schema.js';
 import { MemoryConfigSchema } from './memory-schema.js';
 import { NotificationsConfigSchema } from './notifications-schema.js';
 import { SandboxConfigSchema } from './sandbox-schema.js';
@@ -213,6 +224,7 @@ export const AssistantConfigSchema = z.object({
     .default([]),
   heartbeat: HeartbeatConfigSchema.default({} as any),
   swarm: SwarmConfigSchema.default({} as any),
+  mcp: McpConfigSchema.default({} as any),
   skills: SkillsConfigSchema.default({} as any),
   workspaceGit: WorkspaceGitConfigSchema.default({} as any),
   calls: CallsConfigSchema.default({} as any),

package/src/config/vellum-skills/telegram-setup/SKILL.md

@@ -12,8 +12,9 @@ You are helping your user connect a Telegram bot to the Vellum Assistant gateway
 
 Before beginning setup, verify these conditions are met:
 
-1. **Gateway is running:** Run `curl -sf http://localhost:7830/healthz` — it should return OK. If it fails, tell the user to start the daemon with `vellum daemon start` and wait for it to become healthy before continuing.
+1. **Gateway API base URL is set and reachable:** Use the configured gateway URL in `GATEWAY_BASE_URL` (from Settings "Local Gateway Target"), then run `curl -sf "$GATEWAY_BASE_URL/healthz"` — it should return gateway health JSON (for example `{"status":"ok"}`). If it fails, tell the user to start the daemon with `vellum daemon start` and wait for it to become healthy before continuing.
 2. **Public ingress URL is configured.** The gateway webhook URL is derived from `${ingress.publicBaseUrl}/webhooks/telegram`. If the ingress URL is not configured, load and execute the **public-ingress** skill first (`skill_load` with `skill: "public-ingress"`) to set up an ngrok tunnel and persist the URL before continuing.
+3. **Use gateway control-plane routes only.** Telegram setup/config actions in this skill must call gateway endpoints under `/v1/integrations/telegram/*` — never call the daemon runtime port directly.
 
 ## What You Need
 
@@ -36,7 +37,7 @@ The token is collected securely via a system-level prompt and is never exposed i
 After the token is collected, call the composite setup endpoint which validates the token, stores credentials, and registers bot commands in a single request:
 
 ```bash
-curl -sf -X POST http://localhost:7830/v1/integrations/telegram/setup \
+curl -sf -X POST "$GATEWAY_BASE_URL/v1/integrations/telegram/setup" \
   -H "Authorization: Bearer $(cat ~/.vellum/http-token)" \
   -H "Content-Type: application/json" \
   -d '{}'
@@ -97,7 +98,7 @@ If routing is misconfigured, inbound Telegram messages will be rejected and the
 Before reporting success, confirm the guardian binding was actually created. Check the guardian binding status:
 
 ```bash
-curl -sf http://localhost:7830/v1/integrations/guardian/status?channel=telegram \
+curl -sf "$GATEWAY_BASE_URL/v1/integrations/guardian/status?channel=telegram" \
   -H "Authorization: Bearer $(cat ~/.vellum/http-token)"
 ```
 
@@ -116,7 +117,7 @@ Summarize what was done:
 - Guardian identity: {verified | not configured}
 - Guardian verification status: {verified via outbound flow | skipped}
 - Routing configuration validated
-- To re-check guardian status later, use: `curl -sf http://localhost:7830/v1/integrations/guardian/status?channel=telegram -H "Authorization: Bearer $(cat ~/.vellum/http-token)"`
+- To re-check guardian status later, use: `curl -sf "$GATEWAY_BASE_URL/v1/integrations/guardian/status?channel=telegram" -H "Authorization: Bearer $(cat ~/.vellum/http-token)"`
 
 The gateway automatically detects credentials from the vault, reconciles the Telegram webhook registration, and begins accepting Telegram webhooks shortly. In single-assistant mode, routing is automatically configured — no manual environment variable configuration or webhook registration is needed. If the webhook secret changes later, the gateway's credential watcher will automatically re-register the webhook. If the ingress URL changes (e.g., tunnel restart), the assistant daemon triggers an immediate internal reconcile so the webhook re-registers automatically without a gateway restart.
 

package/src/config/vellum-skills/trusted-contacts/SKILL.md

@@ -10,6 +10,7 @@ You are helping your user manage trusted contacts and invite links for the Vellu
 ## Prerequisites
 
 - The gateway API is available at `http://localhost:7830` (or the configured gateway port).
+- Use gateway control-plane routes only: this skill calls `/v1/ingress/*` and `/v1/integrations/telegram/config` on the gateway, never the daemon runtime port directly.
 - The bearer token is stored at `~/.vellum/http-token`. Read it with: `TOKEN=$(cat ~/.vellum/http-token)`.
 
 ## Concepts

package/src/daemon/lifecycle.ts

@@ -54,6 +54,7 @@ import { createGuardianActionCopyGenerator, createGuardianFollowUpConversationGe
 import { initPairingHandlers } from './handlers/pairing.js';
 import { installCliLaunchers } from './install-cli-launchers.js';
 import type { ServerMessage } from './ipc-protocol.js';
+import { getMcpServerManager } from '../mcp/manager.js';
 import { initializeProvidersAndTools, registerMessagingProviders,registerWatcherProviders } from './providers-setup.js';
 import { seedInterfaceFiles } from './seed-files.js';
 import { DaemonServer } from './server.js';
@@ -398,6 +399,12 @@ export async function runDaemon(): Promise<void> {
     server.setHeartbeatService(heartbeat);
     log.info({ enabled: heartbeatConfig.enabled, intervalMs: heartbeatConfig.intervalMs }, 'Heartbeat service configured');
 
+    // Retrieve the MCP manager if MCP servers were configured.
+    // The manager is a singleton created during initializeProvidersAndTools().
+    const mcpManager = config.mcp?.servers && Object.keys(config.mcp.servers).length > 0
+      ? getMcpServerManager()
+      : null;
+
     installShutdownHandlers({
       server,
       workspaceHeartbeat,
@@ -407,6 +414,7 @@ export async function runDaemon(): Promise<void> {
       scheduler,
       memoryWorker,
       qdrantManager,
+      mcpManager,
       cleanupPidFile,
     });
   } catch (err) {

package/src/daemon/providers-setup.ts

@@ -1,4 +1,5 @@
 import type { AssistantConfig } from '../config/types.js';
+import { getMcpServerManager } from '../mcp/manager.js';
 import { gmailMessagingProvider } from '../messaging/providers/gmail/adapter.js';
 import { slackProvider as slackMessagingProvider } from '../messaging/providers/slack/adapter.js';
 import { smsMessagingProvider } from '../messaging/providers/sms/adapter.js';
@@ -6,7 +7,8 @@ import { telegramBotMessagingProvider } from '../messaging/providers/telegram-bo
 import { whatsappMessagingProvider } from '../messaging/providers/whatsapp/adapter.js';
 import { registerMessagingProvider } from '../messaging/registry.js';
 import { initializeProviders } from '../providers/registry.js';
-import { initializeTools } from '../tools/registry.js';
+import { createMcpToolsFromServer } from '../tools/mcp/mcp-tool-factory.js';
+import { initializeTools, registerMcpTools } from '../tools/registry.js';
 import { getLogger } from '../util/logger.js';
 import { initWatcherEngine } from '../watcher/engine.js';
 import { registerWatcherProvider } from '../watcher/provider-registry.js';
@@ -19,9 +21,32 @@ import { slackProvider as slackWatcherProvider } from '../watcher/providers/slac
 const log = getLogger('lifecycle');
 
 export async function initializeProvidersAndTools(config: AssistantConfig): Promise<void> {
+  console.log('[Daemon] Initializing providers and tools...');
   log.info('Daemon startup: initializing providers and tools');
   initializeProviders(config);
+  console.log('[Daemon] Providers initialized');
   await initializeTools();
+  console.log('[Daemon] Tools initialized');
+
+  // Start MCP servers and register their tools
+  if (config.mcp?.servers && Object.keys(config.mcp.servers).length > 0) {
+    console.log('[MCP] Initializing MCP servers:', Object.keys(config.mcp.servers).join(', '));
+    const manager = getMcpServerManager();
+    try {
+      const serverToolInfos = await manager.start(config.mcp);
+      for (const { serverId, serverConfig, tools } of serverToolInfos) {
+        console.log(`[MCP] Server "${serverId}" connected — discovered ${tools.length} tools:`, tools.map(t => t.name).join(', '));
+        const mcpTools = createMcpToolsFromServer(tools, serverId, serverConfig, manager);
+        registerMcpTools(mcpTools);
+        console.log(`[MCP] Registered ${mcpTools.length} tools from "${serverId}":`, mcpTools.map(t => t.name).join(', '));
+      }
+    } catch (err) {
+      console.error('[MCP] Server initialization failed:', err);
+      log.error({ err }, 'MCP server initialization failed — continuing without MCP tools');
+    }
+  }
+
+  console.log('[Daemon] Providers and tools initialization complete');
   log.info('Daemon startup: providers and tools initialized');
 }
 

package/src/daemon/shutdown-handlers.ts

@@ -3,6 +3,7 @@ import * as Sentry from '@sentry/node';
 import type { HeartbeatService } from '../heartbeat/heartbeat-service.js';
 import type { HookManager } from '../hooks/manager.js';
 import { getSqlite, resetDb } from '../memory/db.js';
+import type { McpServerManager } from '../mcp/manager.js';
 import type { QdrantManager } from '../memory/qdrant-manager.js';
 import type { RuntimeHttpServer } from '../runtime/http-server.js';
 import { browserManager } from '../tools/browser/browser-manager.js';
@@ -22,6 +23,7 @@ export interface ShutdownDeps {
   scheduler: { stop(): void };
   memoryWorker: { stop(): void };
   qdrantManager: QdrantManager;
+  mcpManager: McpServerManager | null;
   cleanupPidFile: () => void;
 }
 
@@ -86,6 +88,15 @@ export function installShutdownHandlers(deps: ShutdownDeps): void {
     await browserManager.closeAllPages();
     deps.scheduler.stop();
     deps.memoryWorker.stop();
+
+    if (deps.mcpManager) {
+      try {
+        await deps.mcpManager.stop();
+      } catch (err) {
+        log.warn({ err }, 'MCP server manager shutdown failed (non-fatal)');
+      }
+    }
+
     await deps.qdrantManager.stop();
 
     // Checkpoint WAL and close SQLite so no writes are lost on exit.

package/src/index.ts

@@ -26,6 +26,7 @@ import {
 import { registerEmailCommand } from './cli/email.js';
 import { registerInfluencerCommand } from './cli/influencer.js';
 import { registerMapCommand } from './cli/map.js';
+import { registerMcpCommand } from './cli/mcp.js';
 import { registerSequenceCommand } from './cli/sequence.js';
 import { registerTwitterCommand } from './cli/twitter.js';
 import { registerHooksCommand } from './hooks/cli.js';
@@ -48,6 +49,7 @@ registerMemoryCommand(program);
 registerAuditCommand(program);
 registerDoctorCommand(program);
 registerHooksCommand(program);
+registerMcpCommand(program);
 registerEmailCommand(program);
 registerAmazonCommand(program);
 registerCompletionsCommand(program);

package/src/mcp/client.ts

@@ -0,0 +1,152 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+
+import type { McpTransport } from '../config/mcp-schema.js';
+import { getLogger } from '../util/logger.js';
+
+const log = getLogger('mcp-client');
+
+const CONNECT_TIMEOUT_MS = 30_000;
+
+export interface McpToolInfo {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+}
+
+export interface McpCallResult {
+  content: string;
+  isError: boolean;
+}
+
+export class McpClient {
+  readonly serverId: string;
+  private client: Client;
+  private transport: StdioClientTransport | SSEClientTransport | StreamableHTTPClientTransport | null = null;
+  private connected = false;
+
+  constructor(serverId: string) {
+    this.serverId = serverId;
+    this.client = new Client({
+      name: 'vellum-assistant',
+      version: '1.0.0',
+    });
+  }
+
+  async connect(transportConfig: McpTransport): Promise<void> {
+    if (this.connected) return;
+
+    console.log(`[MCP] Connecting to server "${this.serverId}"...`);
+    this.transport = this.createTransport(transportConfig);
+    try {
+      await Promise.race([
+        this.client.connect(this.transport),
+        new Promise<never>((_, reject) =>
+          setTimeout(() => reject(new Error(`MCP server "${this.serverId}" connection timed out after ${CONNECT_TIMEOUT_MS}ms`)), CONNECT_TIMEOUT_MS),
+        ),
+      ]);
+    } catch (err) {
+      // Clean up the transport on failure (e.g., kill spawned stdio process)
+      try { await this.client.close(); } catch { /* ignore cleanup errors */ }
+      this.transport = undefined;
+      throw err;
+    }
+    this.connected = true;
+    console.log(`[MCP] Server "${this.serverId}" connected successfully`);
+    log.info({ serverId: this.serverId }, 'MCP client connected');
+  }
+
+  async listTools(): Promise<McpToolInfo[]> {
+    if (!this.connected) {
+      throw new Error(`MCP client "${this.serverId}" is not connected`);
+    }
+
+    const result = await Promise.race([
+      this.client.listTools(),
+      new Promise<never>((_, reject) =>
+        setTimeout(() => reject(new Error(`MCP server "${this.serverId}" listTools timed out after ${CONNECT_TIMEOUT_MS}ms`)), CONNECT_TIMEOUT_MS),
+      ),
+    ]);
+    return result.tools.map((tool) => ({
+      name: tool.name,
+      description: tool.description ?? '',
+      inputSchema: tool.inputSchema as Record<string, unknown>,
+    }));
+  }
+
+  async callTool(name: string, args: Record<string, unknown>): Promise<McpCallResult> {
+    if (!this.connected) {
+      throw new Error(`MCP client "${this.serverId}" is not connected`);
+    }
+
+    const result = await this.client.callTool({ name, arguments: args });
+    const isError = result.isError === true;
+
+    // Handle structuredContent if present
+    if (result.structuredContent !== undefined && result.structuredContent !== null) {
+      return {
+        content: JSON.stringify(result.structuredContent),
+        isError,
+      };
+    }
+
+    // Concatenate all content blocks into a single string
+    const textParts: string[] = [];
+    if (Array.isArray(result.content)) {
+      for (const block of result.content) {
+        if (typeof block === 'object' && block !== null && 'type' in block) {
+          if (block.type === 'text' && 'text' in block) {
+            textParts.push(String(block.text));
+          } else if (block.type === 'resource' && 'resource' in block) {
+            const resource = block.resource as Record<string, unknown>;
+            textParts.push(typeof resource.text === 'string' ? resource.text : JSON.stringify(resource));
+          } else {
+            // For other content types (image, etc.), include type and any available data
+            textParts.push(`[${block.type} content: ${JSON.stringify(block)}]`);
+          }
+        }
+      }
+    }
+
+    return {
+      content: textParts.join('\n') || (isError ? 'Tool execution failed' : 'Tool executed successfully'),
+      isError,
+    };
+  }
+
+  async disconnect(): Promise<void> {
+    if (!this.connected) return;
+
+    try {
+      await this.client.close();
+    } catch (err) {
+      log.warn({ err, serverId: this.serverId }, 'Error closing MCP client');
+    }
+    this.connected = false;
+    this.transport = null;
+    log.info({ serverId: this.serverId }, 'MCP client disconnected');
+  }
+
+  private createTransport(config: McpTransport): StdioClientTransport | SSEClientTransport | StreamableHTTPClientTransport {
+    switch (config.type) {
+      case 'stdio':
+        return new StdioClientTransport({
+          command: config.command,
+          args: config.args,
+          env: config.env ? { ...process.env, ...config.env } as Record<string, string> : undefined,
+        });
+      case 'sse':
+        return new SSEClientTransport(
+          new URL(config.url),
+          { requestInit: config.headers ? { headers: config.headers } : undefined },
+        );
+      case 'streamable-http':
+        return new StreamableHTTPClientTransport(
+          new URL(config.url),
+          { requestInit: config.headers ? { headers: config.headers } : undefined },
+        );
+    }
+  }
+}