agent-orchestrator-mcp-server 0.1.0 → 0.1.2

package/README.md

@@ -9,7 +9,7 @@ MCP server for PulseMCP's agent-orchestrator: a Claude Code + MCP-powered agent-
 
 - Simplified 4-tool interface for full agent session management
 - Search, filter, and retrieve sessions with optional logs and transcripts
-- Session lifecycle actions (pause, restart, archive, unarchive, follow_up)
+- Session lifecycle actions (pause, restart, archive, unarchive, follow_up, change_mcp_servers)
 - Tool grouping system for permission-based access control
 - TypeScript with strict type checking
 - Comprehensive testing setup (functional, integration, manual)
@@ -18,12 +18,12 @@ MCP server for PulseMCP's agent-orchestrator: a Claude Code + MCP-powered agent-
 
 ### Tools
 
-| Tool              | Group    | Description                                                            |
-| ----------------- | -------- | ---------------------------------------------------------------------- |
-| `search_sessions` | readonly | Search/list sessions with optional ID lookup, query, and status filter |
-| `get_session`     | readonly | Get detailed session info with optional logs and transcripts           |
-| `start_session`   | write    | Create and start a new agent session                                   |
-| `action_session`  | write    | Perform actions: follow_up, pause, restart, archive, unarchive         |
+| Tool              | Group    | Description                                                                        |
+| ----------------- | -------- | ---------------------------------------------------------------------------------- |
+| `search_sessions` | readonly | Search/list sessions with optional ID lookup, query, and status filter             |
+| `get_session`     | readonly | Get detailed session info with optional logs and transcripts                       |
+| `start_session`   | write    | Create and start a new agent session                                               |
+| `action_session`  | write    | Perform actions: follow_up, pause, restart, archive, unarchive, change_mcp_servers |
 
 ### Resources
 
@@ -47,51 +47,45 @@ Control which tools are available via the `ENABLED_TOOLGROUPS` environment varia
 - `ENABLED_TOOLGROUPS="readonly,write"` - Read and write, no admin
 - Not set - All tools enabled (default)
 
-## Quick Start
+## Setup
 
-### Installation
+### Prerequisites
 
-```bash
-npm run install-all
-npm run build
-```
+- Node.js (use `nvm use` if you have nvm installed)
+- An Agent Orchestrator instance with API access
 
-### Configuration
+### Environment Variables
 
-Set the required environment variables:
+| Variable                      | Required | Description                            | Default     |
+| ----------------------------- | -------- | -------------------------------------- | ----------- |
+| `AGENT_ORCHESTRATOR_BASE_URL` | Yes      | Base URL for the orchestrator API      | -           |
+| `AGENT_ORCHESTRATOR_API_KEY`  | Yes      | API key for authentication             | -           |
+| `ENABLED_TOOLGROUPS`          | No       | Comma-separated tool groups            | All enabled |
+| `SKIP_HEALTH_CHECKS`          | No       | Skip API connectivity check at startup | `false`     |
+| `HEALTH_CHECK_TIMEOUT`        | No       | Health check timeout in milliseconds   | `10000`     |
 
-```bash
-export AGENT_ORCHESTRATOR_BASE_URL="http://localhost:3000"
-export AGENT_ORCHESTRATOR_API_KEY="your_api_key_here"
-```
+### Claude Desktop
 
-### Running
+Make sure you have your Agent Orchestrator base URL and API key ready.
 
-```bash
-npm start
-```
+Then proceed to the setup instructions below. If this is your first time using MCP Servers, you'll want to make sure you have the [Claude Desktop application](https://claude.ai/download) and follow the [official MCP setup instructions](https://modelcontextprotocol.io/quickstart/user).
 
-## Environment Variables
+#### Manual Setup
 
-| Variable                      | Required | Description                       | Default     |
-| ----------------------------- | -------- | --------------------------------- | ----------- |
-| `AGENT_ORCHESTRATOR_BASE_URL` | Yes      | Base URL for the orchestrator API | -           |
-| `AGENT_ORCHESTRATOR_API_KEY`  | Yes      | API key for authentication        | -           |
-| `ENABLED_TOOLGROUPS`          | No       | Comma-separated tool groups       | All enabled |
-| `SKIP_HEALTH_CHECKS`          | No       | Skip API validation at startup    | `false`     |
+You're going to need Node working on your machine so you can run `npx` commands in your terminal. If you don't have Node, you can install it from [nodejs.org](https://nodejs.org/en/download).
 
-### Claude Desktop Configuration
+macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
 
-#### macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+Windows: `%APPDATA%\Claude\claude_desktop_config.json`
 
-#### Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+Modify your `claude_desktop_config.json` file to add the following:
 
 ```json
 {
   "mcpServers": {
     "agent-orchestrator": {
-      "command": "node",
-      "args": ["/path/to/agent-orchestrator/local/build/index.js"],
+      "command": "npx",
+      "args": ["-y", "agent-orchestrator-mcp-server"],
       "env": {
         "AGENT_ORCHESTRATOR_BASE_URL": "http://localhost:3000",
         "AGENT_ORCHESTRATOR_API_KEY": "your-api-key-here",
@@ -102,6 +96,8 @@ npm start
 }
 ```
 
+Restart Claude Desktop and you should be ready to go!
+
 ## Development
 
 ### Running in Development Mode

package/build/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { createMCPServer } from '../shared/index.js';
-import { logServerStart, logError, logWarning } from '../shared/logging.js';
+import { createMCPServer, checkApiHealth, getErrorHint, parseHealthCheckTimeout, } from '../shared/index.js';
+import { logServerStart, logError, logWarning, logDebug } from '../shared/logging.js';
 // =============================================================================
 // ENVIRONMENT VALIDATION
 // =============================================================================
@@ -28,9 +28,14 @@ function validateEnvironment() {
         },
         {
             name: 'SKIP_HEALTH_CHECKS',
-            description: 'Skip API validation at startup',
+            description: 'Skip API connectivity check at startup (set to "true" to skip)',
             defaultValue: 'false',
         },
+        {
+            name: 'HEALTH_CHECK_TIMEOUT',
+            description: 'Health check timeout in milliseconds',
+            defaultValue: '10000',
+        },
     ];
     const missing = required.filter(({ name }) => !process.env[name]);
     if (missing.length > 0) {
@@ -71,8 +76,28 @@ async function performHealthChecks() {
         logWarning('healthcheck', 'Health checks skipped (SKIP_HEALTH_CHECKS=true)');
         return;
     }
-    // For agent-orchestrator, we could add a health check by calling the sessions endpoint
-    // For now, we skip complex validation since the API might not always be available
+    logDebug('healthcheck', 'Performing API connectivity health check...');
+    // Parse health check timeout using shared utility
+    const healthCheckTimeout = parseHealthCheckTimeout(process.env.HEALTH_CHECK_TIMEOUT, (msg) => logWarning('healthcheck', msg));
+    const baseUrl = process.env.AGENT_ORCHESTRATOR_BASE_URL;
+    const apiKey = process.env.AGENT_ORCHESTRATOR_API_KEY;
+    try {
+        await checkApiHealth(baseUrl, apiKey, healthCheckTimeout);
+        logDebug('healthcheck', `Health check passed - connected to ${baseUrl}`);
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        // Provide helpful error messages based on common failure scenarios
+        const hint = getErrorHint(errorMessage, healthCheckTimeout);
+        logError('healthcheck', `API connectivity health check failed: ${errorMessage}${hint}`);
+        console.error('\n----------------------------------------');
+        console.error('API connectivity health check failed!');
+        console.error(`Error: ${errorMessage}${hint}`);
+        console.error('\nTo skip health checks, set:');
+        console.error('  SKIP_HEALTH_CHECKS=true');
+        console.error('----------------------------------------\n');
+        process.exit(1);
+    }
 }
 // =============================================================================
 // MAIN ENTRY POINT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-orchestrator-mcp-server",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Local implementation of agent-orchestrator MCP server",
   "main": "build/index.js",
   "type": "module",

package/shared/health-check.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Health check utilities for Agent Orchestrator MCP server.
+ * These are exported separately for testing.
+ */
+export declare const DEFAULT_HEALTH_CHECK_TIMEOUT = 10000;
+export declare const MAX_HEALTH_CHECK_TIMEOUT = 300000;
+/**
+ * Get a helpful hint based on the error message to guide users in troubleshooting.
+ */
+export declare function getErrorHint(errorMessage: string, timeout: number): string;
+/**
+ * Parse and validate health check timeout from environment variable.
+ * Returns validated timeout value or default.
+ */
+export declare function parseHealthCheckTimeout(envValue: string | undefined, warnFn?: (message: string) => void): number;
+/**
+ * Perform a health check against the Agent Orchestrator API.
+ * Makes a lightweight request to verify connectivity and authentication.
+ */
+export declare function checkApiHealth(baseUrl: string, apiKey: string, timeoutMs?: number): Promise<void>;
+//# sourceMappingURL=health-check.d.ts.map

package/shared/health-check.js

@@ -0,0 +1,115 @@
+/**
+ * Health check utilities for Agent Orchestrator MCP server.
+ * These are exported separately for testing.
+ */
+export const DEFAULT_HEALTH_CHECK_TIMEOUT = 10000;
+export const MAX_HEALTH_CHECK_TIMEOUT = 300000; // 5 minutes max
+/**
+ * Get a helpful hint based on the error message to guide users in troubleshooting.
+ */
+export function getErrorHint(errorMessage, timeout) {
+    // Check for authentication errors first (most common initial setup issue)
+    if (errorMessage.includes('401') ||
+        errorMessage.includes('403') ||
+        errorMessage.toLowerCase().includes('unauthorized') ||
+        errorMessage.toLowerCase().includes('forbidden')) {
+        return '\nHint: Authentication failed. Check that AGENT_ORCHESTRATOR_API_KEY is correct.';
+    }
+    // Check for timeout errors
+    if (errorMessage.toLowerCase().includes('timeout')) {
+        return `\nHint: Connection timed out after ${timeout}ms. Check that the API server is running and reachable.`;
+    }
+    // Check for connection refused (specific error codes)
+    if (errorMessage.includes('ECONNREFUSED')) {
+        return '\nHint: Connection refused. Check that the API server is running and AGENT_ORCHESTRATOR_BASE_URL is correct.';
+    }
+    // Check for DNS resolution errors
+    if (errorMessage.includes('ENOTFOUND') || errorMessage.includes('getaddrinfo')) {
+        return '\nHint: Could not resolve hostname. Check that AGENT_ORCHESTRATOR_BASE_URL is correct.';
+    }
+    // Check for other connection errors (more specific patterns)
+    if (errorMessage.includes('ECONNRESET') ||
+        errorMessage.includes('EHOSTUNREACH') ||
+        errorMessage.includes('ENETUNREACH')) {
+        return '\nHint: Network error. Check that the API server is reachable and there are no firewall issues.';
+    }
+    // Check for invalid URL errors
+    if (errorMessage.includes('Invalid URL') || errorMessage.includes('ERR_INVALID_URL')) {
+        return '\nHint: Invalid URL. Check that AGENT_ORCHESTRATOR_BASE_URL is a valid URL (e.g., http://localhost:3000).';
+    }
+    return '';
+}
+/**
+ * Parse and validate health check timeout from environment variable.
+ * Returns validated timeout value or default.
+ */
+export function parseHealthCheckTimeout(envValue, warnFn) {
+    if (!envValue) {
+        return DEFAULT_HEALTH_CHECK_TIMEOUT;
+    }
+    const parsed = parseInt(envValue, 10);
+    if (!isNaN(parsed) && parsed > 0 && parsed <= MAX_HEALTH_CHECK_TIMEOUT) {
+        return parsed;
+    }
+    if (warnFn) {
+        warnFn(`Invalid HEALTH_CHECK_TIMEOUT: ${envValue}. Must be between 1 and ${MAX_HEALTH_CHECK_TIMEOUT}. Using default: ${DEFAULT_HEALTH_CHECK_TIMEOUT}ms`);
+    }
+    return DEFAULT_HEALTH_CHECK_TIMEOUT;
+}
+/**
+ * Perform a health check against the Agent Orchestrator API.
+ * Makes a lightweight request to verify connectivity and authentication.
+ */
+export async function checkApiHealth(baseUrl, apiKey, timeoutMs = DEFAULT_HEALTH_CHECK_TIMEOUT) {
+    // Validate inputs
+    if (!baseUrl || baseUrl.trim().length === 0) {
+        throw new Error('Base URL cannot be empty');
+    }
+    if (!apiKey || apiKey.trim().length === 0) {
+        throw new Error('API key cannot be empty');
+    }
+    // Remove trailing slash if present
+    const normalizedBaseUrl = baseUrl.trim().replace(/\/$/, '');
+    // Use the sessions endpoint with minimal data to verify connectivity
+    let url;
+    try {
+        url = new URL(`${normalizedBaseUrl}/api/v1/sessions`);
+    }
+    catch {
+        throw new Error('Invalid URL: Check that AGENT_ORCHESTRATOR_BASE_URL is a valid URL (e.g., http://localhost:3000)');
+    }
+    url.searchParams.set('per_page', '1');
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(url.toString(), {
+            method: 'GET',
+            headers: {
+                'X-API-Key': apiKey.trim(),
+                'Content-Type': 'application/json',
+            },
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            let errorMessage;
+            try {
+                const errorJson = JSON.parse(errorText);
+                errorMessage = errorJson.message || errorJson.error || errorText;
+            }
+            catch {
+                errorMessage = errorText || `HTTP ${response.status}`;
+            }
+            throw new Error(`API Error (${response.status}): ${errorMessage}`);
+        }
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === 'AbortError') {
+            throw new Error(`Request timeout after ${timeoutMs}ms`);
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}

package/shared/index.d.ts

@@ -2,6 +2,7 @@ export { registerResources } from './resources.js';
 export { registerTools, createRegisterTools, type ToolGroup, parseEnabledToolGroups, } from './tools.js';
 export { createMCPServer, type ClientFactory, type IAgentOrchestratorClient } from './server.js';
 export { AgentOrchestratorClient, type IAgentOrchestratorClient as AgentOrchestratorClientInterface, } from './orchestrator-client/orchestrator-client.js';
+export { checkApiHealth, getErrorHint, parseHealthCheckTimeout, DEFAULT_HEALTH_CHECK_TIMEOUT, MAX_HEALTH_CHECK_TIMEOUT, } from './health-check.js';
 export type { Session, Log, SubagentTranscript, SessionStatus, LogLevel, SubagentStatus, Pagination, SessionsResponse, SearchSessionsResponse, SessionResponse, SessionActionResponse, LogsResponse, LogResponse, SubagentTranscriptsResponse, SubagentTranscriptResponse, CreateSessionRequest, UpdateSessionRequest, CreateLogRequest, UpdateLogRequest, CreateSubagentTranscriptRequest, UpdateSubagentTranscriptRequest, } from './types.js';
 export { logServerStart, logError, logWarning, logDebug } from './logging.js';
 //# sourceMappingURL=index.d.ts.map

package/shared/index.js

@@ -4,5 +4,7 @@ export { registerTools, createRegisterTools, parseEnabledToolGroups, } from './t
 export { createMCPServer } from './server.js';
 // Client exports
 export { AgentOrchestratorClient, } from './orchestrator-client/orchestrator-client.js';
+// Health check exports
+export { checkApiHealth, getErrorHint, parseHealthCheckTimeout, DEFAULT_HEALTH_CHECK_TIMEOUT, MAX_HEALTH_CHECK_TIMEOUT, } from './health-check.js';
 // Logging exports (re-exported for convenience)
 export { logServerStart, logError, logWarning, logDebug } from './logging.js';

package/shared/orchestrator-client/orchestrator-client.d.ts

@@ -33,6 +33,7 @@ export interface IAgentOrchestratorClient {
     followUp(id: string | number, prompt: string): Promise<SessionActionResponse>;
     pauseSession(id: string | number): Promise<SessionActionResponse>;
     restartSession(id: string | number): Promise<SessionActionResponse>;
+    changeMcpServers(id: string | number, mcp_servers: string[]): Promise<Session>;
     listLogs(sessionId: string | number, options?: {
         level?: LogLevel;
         page?: number;
@@ -86,6 +87,7 @@ export declare class AgentOrchestratorClient implements IAgentOrchestratorClient
     followUp(id: string | number, prompt: string): Promise<SessionActionResponse>;
     pauseSession(id: string | number): Promise<SessionActionResponse>;
     restartSession(id: string | number): Promise<SessionActionResponse>;
+    changeMcpServers(id: string | number, mcp_servers: string[]): Promise<Session>;
     listLogs(sessionId: string | number, options?: {
         level?: LogLevel;
         page?: number;

package/shared/orchestrator-client/orchestrator-client.integration-mock.js

@@ -171,6 +171,8 @@ export function createIntegrationMockOrchestratorClient(initialMockData) {
                 session.slug = data.slug;
             if (data.stop_condition !== undefined)
                 session.stop_condition = data.stop_condition;
+            if (data.mcp_servers !== undefined)
+                session.mcp_servers = data.mcp_servers;
             if (data.custom_metadata !== undefined)
                 session.custom_metadata = data.custom_metadata;
             session.updated_at = new Date().toISOString();
@@ -237,6 +239,15 @@ export function createIntegrationMockOrchestratorClient(initialMockData) {
             session.updated_at = new Date().toISOString();
             return { session, message: 'Session restarted' };
         },
+        async changeMcpServers(id, mcp_servers) {
+            const session = mockData.sessions?.find((s) => s.id === Number(id) || s.slug === String(id));
+            if (!session) {
+                throw new Error(`API Error (404): Session not found`);
+            }
+            session.mcp_servers = mcp_servers;
+            session.updated_at = new Date().toISOString();
+            return session;
+        },
         async listLogs(sessionId, options) {
             let logs = (mockData.logs || []).filter((l) => l.session_id === Number(sessionId));
             if (options?.level) {

package/shared/orchestrator-client/orchestrator-client.js

@@ -125,6 +125,12 @@ export class AgentOrchestratorClient {
     async restartSession(id) {
         return this.request('POST', `/sessions/${id}/restart`);
     }
+    async changeMcpServers(id, mcp_servers) {
+        const response = await this.request('PATCH', `/sessions/${id}`, {
+            mcp_servers,
+        });
+        return response.session;
+    }
     // Logs
     async listLogs(sessionId, options) {
         return this.request('GET', `/sessions/${sessionId}/logs`, undefined, options);

package/shared/tools/action-session.d.ts

@@ -3,16 +3,19 @@ import { z } from 'zod';
 import type { IAgentOrchestratorClient } from '../orchestrator-client/orchestrator-client.js';
 export declare const ActionSessionSchema: z.ZodObject<{
     session_id: z.ZodUnion<[z.ZodString, z.ZodNumber]>;
-    action: z.ZodEnum<["follow_up", "pause", "restart", "archive", "unarchive"]>;
+    action: z.ZodEnum<["follow_up", "pause", "restart", "archive", "unarchive", "change_mcp_servers"]>;
     prompt: z.ZodOptional<z.ZodString>;
+    mcp_servers: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
 }, "strip", z.ZodTypeAny, {
     session_id: string | number;
-    action: "follow_up" | "pause" | "restart" | "archive" | "unarchive";
+    action: "follow_up" | "pause" | "restart" | "archive" | "unarchive" | "change_mcp_servers";
     prompt?: string | undefined;
+    mcp_servers?: string[] | undefined;
 }, {
     session_id: string | number;
-    action: "follow_up" | "pause" | "restart" | "archive" | "unarchive";
+    action: "follow_up" | "pause" | "restart" | "archive" | "unarchive" | "change_mcp_servers";
     prompt?: string | undefined;
+    mcp_servers?: string[] | undefined;
 }>;
 export declare function actionSessionTool(_server: Server, clientFactory: () => IAgentOrchestratorClient): {
     name: string;
@@ -28,13 +31,20 @@ export declare function actionSessionTool(_server: Server, clientFactory: () =>
             };
             action: {
                 type: string;
-                enum: readonly ["follow_up", "pause", "restart", "archive", "unarchive"];
-                description: "Action to perform: \"follow_up\" (send prompt to paused session), \"pause\" (pause running session), \"restart\" (restart paused/failed session), \"archive\" (archive session), \"unarchive\" (restore archived session)";
+                enum: readonly ["follow_up", "pause", "restart", "archive", "unarchive", "change_mcp_servers"];
+                description: "Action to perform: \"follow_up\" (send prompt to paused session), \"pause\" (pause running session), \"restart\" (restart paused/failed session), \"archive\" (archive session), \"unarchive\" (restore archived session), \"change_mcp_servers\" (update MCP servers for session)";
             };
             prompt: {
                 type: string;
                 description: "Required for \"follow_up\" action. The prompt to send to the agent. Not used for other actions.";
             };
+            mcp_servers: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: "Required for \"change_mcp_servers\" action. Array of MCP server names to set for the session.";
+            };
         };
         required: string[];
     };

package/shared/tools/action-session.js

@@ -1,14 +1,23 @@
 import { z } from 'zod';
 const PARAM_DESCRIPTIONS = {
     session_id: 'Session ID (numeric) or slug (string) to perform the action on.',
-    action: 'Action to perform: "follow_up" (send prompt to paused session), "pause" (pause running session), "restart" (restart paused/failed session), "archive" (archive session), "unarchive" (restore archived session)',
+    action: 'Action to perform: "follow_up" (send prompt to paused session), "pause" (pause running session), "restart" (restart paused/failed session), "archive" (archive session), "unarchive" (restore archived session), "change_mcp_servers" (update MCP servers for session)',
     prompt: 'Required for "follow_up" action. The prompt to send to the agent. Not used for other actions.',
+    mcp_servers: 'Required for "change_mcp_servers" action. Array of MCP server names to set for the session.',
 };
-const ACTION_ENUM = ['follow_up', 'pause', 'restart', 'archive', 'unarchive'];
+const ACTION_ENUM = [
+    'follow_up',
+    'pause',
+    'restart',
+    'archive',
+    'unarchive',
+    'change_mcp_servers',
+];
 export const ActionSessionSchema = z.object({
     session_id: z.union([z.string(), z.number()]).describe(PARAM_DESCRIPTIONS.session_id),
     action: z.enum(ACTION_ENUM).describe(PARAM_DESCRIPTIONS.action),
     prompt: z.string().optional().describe(PARAM_DESCRIPTIONS.prompt),
+    mcp_servers: z.array(z.string()).optional().describe(PARAM_DESCRIPTIONS.mcp_servers),
 });
 const TOOL_DESCRIPTION = `Perform an action on an agent session.
 
@@ -18,6 +27,7 @@ const TOOL_DESCRIPTION = `Perform an action on an agent session.
 - **restart**: Restart a paused or failed session without providing new input
 - **archive**: Archive a session (marks as completed)
 - **unarchive**: Restore an archived session to "needs_input" status
+- **change_mcp_servers**: Update the MCP servers for a session (requires "mcp_servers" parameter)
 
 **Status requirements:**
 - follow_up: Session must be "needs_input"
@@ -25,11 +35,13 @@ const TOOL_DESCRIPTION = `Perform an action on an agent session.
 - restart: Session must be "needs_input" or "failed"
 - archive: Session can be in any status except "archived"
 - unarchive: Session must be "archived"
+- change_mcp_servers: Session can be in any status except "archived"
 
 **Use cases:**
 - Provide additional instructions to an agent
 - Control session lifecycle (pause, restart)
-- Organize sessions (archive, unarchive)`;
+- Organize sessions (archive, unarchive)
+- Reconfigure session MCP server access`;
 export function actionSessionTool(_server, clientFactory) {
     return {
         name: 'action_session',
@@ -50,6 +62,11 @@ export function actionSessionTool(_server, clientFactory) {
                     type: 'string',
                     description: PARAM_DESCRIPTIONS.prompt,
                 },
+                mcp_servers: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: PARAM_DESCRIPTIONS.mcp_servers,
+                },
             },
             required: ['session_id', 'action'],
         },
@@ -57,7 +74,7 @@ export function actionSessionTool(_server, clientFactory) {
             try {
                 const validatedArgs = ActionSessionSchema.parse(args);
                 const client = clientFactory();
-                const { session_id, action, prompt } = validatedArgs;
+                const { session_id, action, prompt, mcp_servers } = validatedArgs;
                 // Validate that prompt is provided for follow_up action
                 if (action === 'follow_up' && !prompt) {
                     return {
@@ -70,6 +87,18 @@ export function actionSessionTool(_server, clientFactory) {
                         isError: true,
                     };
                 }
+                // Validate that mcp_servers is provided for change_mcp_servers action
+                if (action === 'change_mcp_servers' && !mcp_servers) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: 'Error: The "mcp_servers" parameter is required for the "change_mcp_servers" action.',
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
                 let result;
                 switch (action) {
                     case 'follow_up': {
@@ -148,6 +177,18 @@ export function actionSessionTool(_server, clientFactory) {
                         result = lines.join('\n');
                         break;
                     }
+                    case 'change_mcp_servers': {
+                        const session = await client.changeMcpServers(session_id, mcp_servers);
+                        const lines = [
+                            `## MCP Servers Updated`,
+                            '',
+                            `- **Session ID:** ${session.id}`,
+                            `- **Title:** ${session.title}`,
+                            `- **MCP Servers:** ${session.mcp_servers.length > 0 ? session.mcp_servers.join(', ') : '(none)'}`,
+                        ];
+                        result = lines.join('\n');
+                        break;
+                    }
                     default: {
                         // This should never happen due to Zod validation
                         const _exhaustiveCheck = action;

package/shared/tools/search-sessions.d.ts

@@ -11,20 +11,20 @@ export declare const SearchSessionsSchema: z.ZodObject<{
     page: z.ZodOptional<z.ZodNumber>;
     per_page: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
+    per_page?: number | undefined;
     status?: "waiting" | "running" | "needs_input" | "failed" | "archived" | undefined;
     agent_type?: string | undefined;
     show_archived?: boolean | undefined;
     page?: number | undefined;
-    per_page?: number | undefined;
     search_contents?: boolean | undefined;
     id?: number | undefined;
     query?: string | undefined;
 }, {
+    per_page?: number | undefined;
     status?: "waiting" | "running" | "needs_input" | "failed" | "archived" | undefined;
     agent_type?: string | undefined;
     show_archived?: boolean | undefined;
     page?: number | undefined;
-    per_page?: number | undefined;
     search_contents?: boolean | undefined;
     id?: number | undefined;
     query?: string | undefined;

package/shared/types.d.ts

@@ -116,6 +116,7 @@ export interface UpdateSessionRequest {
     title?: string;
     slug?: string;
     stop_condition?: string;
+    mcp_servers?: string[];
     custom_metadata?: Record<string, unknown>;
 }
 export interface CreateLogRequest {