@letta-ai/letta-agent-sdk 0.5.6 → 0.5.8

package/README.md

@@ -123,27 +123,44 @@ Local execution (embedded Letta Code harness / app server) requires Node.js 22.1
 
 ### MCP tools
 
-Pass stdio MCP servers as session options. The SDK starts them in the session
-cwd, namespaces their tools as `mcp__<server>__<tool>`, and exposes them through
-Letta Code's external-tool protocol. Servers are closed with the session.
+Pass MCP servers by name in session options. The SDK supports local stdio,
+Streamable HTTP, and legacy SSE transports. It namespaces discovered tools as
+`mcp__<server>__<tool>` and exposes them through Letta Code's external-tool
+protocol.
 
 ```ts
 await using session = client.createSession(agentId, {
   cwd: process.cwd(),
-  mcpServers: [
-    {
-      name: "filesystem",
+  mcpServers: {
+    filesystem: {
       command: "npx",
       args: ["-y", "@modelcontextprotocol/server-filesystem", process.cwd()],
     },
-  ],
+    exa: {
+      type: "http",
+      url: "https://mcp.exa.ai/mcp",
+    },
+    github: {
+      type: "http",
+      url: "https://api.githubcopilot.com/mcp/",
+      headers: {
+        Authorization: `Bearer ${process.env.GITHUB_TOKEN}`,
+      },
+    },
+  },
+  allowedTools: ["mcp__filesystem__*", "mcp__exa__*", "mcp__github__list_issues"],
 });
 ```
 
-MCP stdio processes require the Node package entry; they are not available from
-`@letta-ai/letta-agent-sdk/client` in browser or React Native environments. For
-a simple smoke test, the official `@modelcontextprotocol/server-everything`
-package runs over stdio with `npx -y @modelcontextprotocol/server-everything`.
+Connections start concurrently during session initialization. A failed server
+is skipped without dropping healthy servers. OAuth is host-managed, matching
+the Claude Agent SDK: complete OAuth in your application and provide the access
+token through `headers`. The SDK does not open an interactive browser flow.
+
+MCP connections run in the Node SDK process and close with the session. This
+includes MCP used by remote and Cloud sessions: stdio servers see the SDK host
+filesystem, not a managed sandbox. MCP is unavailable from the portable
+`@letta-ai/letta-agent-sdk/client` browser and React Native entry point.
 
 ### Managed Cloud sandbox repositories
 

package/dist/app-server-session.d.ts

@@ -67,12 +67,15 @@ export declare class AppServerSession extends RemoteClientSessionCore {
     private ownedConnection;
     private externalTools;
     private mcpBridge;
+    private mcpCleanup;
     private removeExternalToolHandler;
     private removeControlRequestHandler;
     constructor(remoteOptions: AppServerSessionOptions, mode: AppServerSessionMode);
     protected shouldEnableMemfs(options: LettaCodeClientSessionOptions | CreateAgentOptions): boolean;
     protected initializeRuntimeController(): Promise<RuntimeSessionInit>;
     protected onCoreClose(): void;
+    protected onCoreDisposed(): Promise<void>;
+    private closeMcpBridge;
     private resolveAppServerUrl;
     private startRuntime;
     private buildRuntimeStartCommand;

package/dist/app-server-session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app-server-session.d.ts","sourceRoot":"","sources":["../src/app-server-session.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"app-server-session.d.ts","sourceRoot":"","sources":["../src/app-server-session.ts"],"names":[],"mappings":"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"}

package/dist/client-entry.js

@@ -8618,16 +8618,31 @@ function buildCanUseToolContext(request, requestId) {
 // src/mcp-runtime.ts
 var connector = null;
 async function connectMcpServers(servers, options = {}) {
-  if (!servers || servers.length === 0) {
+  if (!servers || Object.keys(servers).length === 0) {
     return { tools: [], close: async () => {
       return;
     } };
   }
   if (!connector) {
-    throw new Error("MCP stdio servers require the Node package entry '@letta-ai/letta-agent-sdk'; they are not available from '@letta-ai/letta-agent-sdk/client'.");
+    throw new Error("MCP servers require the Node package entry '@letta-ai/letta-agent-sdk'; they are not available from '@letta-ai/letta-agent-sdk/client'.");
   }
   return connector(servers, options);
 }
+function expandMcpToolWildcards(allowedTools, mcpTools) {
+  if (allowedTools === undefined)
+    return;
+  const available = [...mcpTools];
+  const expanded = [];
+  for (const entry of allowedTools) {
+    if (entry.startsWith("mcp__") && entry.endsWith("*")) {
+      const prefix = entry.slice(0, -1);
+      expanded.push(...available.filter((name) => name.startsWith(prefix)));
+    } else {
+      expanded.push(entry);
+    }
+  }
+  return [...new Set(expanded)];
+}
 
 // src/remote-session-protocol.ts
 var FAILURE_STOP_REASONS = new Set([
@@ -9836,6 +9851,7 @@ class RemoteClientSessionCore {
   }
   async[Symbol.asyncDispose]() {
     this.close();
+    await this.onCoreDisposed();
   }
   async changeDeviceState(updates) {
     if (!this.initialized) {
@@ -9877,6 +9893,7 @@ class RemoteClientSessionCore {
   async afterRuntimeInitialized() {}
   async beforeTurn() {}
   onCoreClose() {}
+  async onCoreDisposed() {}
   currentOptions() {
     return this.mode.options;
   }
@@ -10126,7 +10143,8 @@ function createExternalToolCallHandler(externalTools) {
         ...part.text !== undefined ? { text: part.text } : {},
         ...part.data !== undefined ? { data: part.data } : {},
         ...part.mimeType !== undefined ? { mimeType: part.mimeType } : {}
-      }))
+      })),
+      ...result.isError === true ? { is_error: true } : {}
     };
   };
 }
@@ -10418,6 +10436,7 @@ class AppServerSession extends RemoteClientSessionCore {
   ownedConnection = null;
   externalTools = new Map;
   mcpBridge = null;
+  mcpCleanup = Promise.resolve();
   removeExternalToolHandler = null;
   removeControlRequestHandler = null;
   constructor(remoteOptions, mode) {
@@ -10437,6 +10456,7 @@ class AppServerSession extends RemoteClientSessionCore {
     return options.memfs !== false;
   }
   async initializeRuntimeController() {
+    await this.mcpCleanup;
     const url = await this.resolveAppServerUrl();
     const client = applyUniqueRequestIds(createAppServerClient({
       url,
@@ -10468,12 +10488,15 @@ class AppServerSession extends RemoteClientSessionCore {
       }
       const tools = agentToolNames(response.agent);
       const skillSources = this.currentOptions().skillSources;
+      const mcpToolNames = this.mcpBridge?.tools.map((tool) => tool.name) ?? [];
+      const allowedTools = expandMcpToolWildcards(this.currentOptions().allowedTools, mcpToolNames);
+      const availableTools = tools === undefined && mcpToolNames.length === 0 ? undefined : [...tools ?? [], ...mcpToolNames];
       return {
-        controller: new AppServerRuntimeController(client, this.remoteOptions, this.currentOptions().allowedTools),
+        controller: new AppServerRuntimeController(client, this.remoteOptions, allowedTools),
         runtime: response.runtime,
         model: typeof response.agent?.model === "string" ? response.agent.model : "",
         modelSettings: objectRecord(response.agent?.model_settings) ?? null,
-        ...tools !== undefined ? { tools } : {},
+        ...availableTools !== undefined ? { tools: availableTools } : {},
         ...skillSources !== undefined ? { skillSources: [...skillSources] } : {}
       };
     } catch (error) {
@@ -10481,8 +10504,7 @@ class AppServerSession extends RemoteClientSessionCore {
       this.removeExternalToolHandler = null;
       this.removeControlRequestHandler?.();
       this.removeControlRequestHandler = null;
-      this.mcpBridge?.close();
-      this.mcpBridge = null;
+      await this.closeMcpBridge();
       client.close();
       throw error;
     }
@@ -10492,11 +10514,20 @@ class AppServerSession extends RemoteClientSessionCore {
     this.removeExternalToolHandler = null;
     this.removeControlRequestHandler?.();
     this.removeControlRequestHandler = null;
-    this.mcpBridge?.close();
-    this.mcpBridge = null;
+    this.mcpCleanup = this.closeMcpBridge();
     this.ownedConnection?.close();
     this.ownedConnection = null;
   }
+  async onCoreDisposed() {
+    await this.mcpCleanup;
+  }
+  closeMcpBridge() {
+    const bridge = this.mcpBridge;
+    this.mcpBridge = null;
+    for (const tool of bridge?.tools ?? [])
+      this.externalTools.delete(tool.name);
+    return bridge?.close() ?? Promise.resolve();
+  }
   async resolveAppServerUrl() {
     if (this.remoteOptions.url) {
       return this.remoteOptions.url;
@@ -11152,6 +11183,7 @@ class CloudEnvironmentSession extends RemoteClientSessionCore {
   removeControlRequestHandler = null;
   externalTools = new Map;
   mcpBridge = null;
+  mcpCleanup = Promise.resolve();
   managedSandbox = null;
   sandboxRefreshTimer = null;
   sandboxRefreshInFlight = null;
@@ -11173,6 +11205,7 @@ class CloudEnvironmentSession extends RemoteClientSessionCore {
     this.externalTools = externalToolsByName(tools);
   }
   async initializeRuntimeController() {
+    await this.mcpCleanup;
     const resolved = await this.resolveRuntime();
     const connection = await this.resolveConnectionForRuntime(resolved.runtime).catch(async (error) => {
       await this.cleanupSessionRepositories(resolved.runtime.agent_id, resolved.runtime.conversation_id);
@@ -11223,14 +11256,17 @@ class CloudEnvironmentSession extends RemoteClientSessionCore {
       }
       const tools = agentToolNames(response.agent);
       const skillSources = this.currentOptions().skillSources;
+      const mcpToolNames = this.mcpBridge?.tools.map((tool) => tool.name) ?? [];
+      const allowedTools = expandMcpToolWildcards(this.currentOptions().allowedTools, mcpToolNames);
+      const availableTools = tools === undefined && mcpToolNames.length === 0 ? undefined : [...tools ?? [], ...mcpToolNames];
       return {
         controller: new AppServerRuntimeController(client, {
           requestTimeoutMs: this.cloudOptions.requestTimeoutMs ?? DEFAULT_TURN_TIMEOUT_MS
-        }, this.currentOptions().allowedTools),
+        }, allowedTools),
         runtime: response.runtime,
         model: typeof response.agent?.model === "string" ? response.agent.model : "",
         modelSettings: response.agent?.model_settings ?? null,
-        ...tools !== undefined ? { tools } : {},
+        ...availableTools !== undefined ? { tools: availableTools } : {},
         ...skillSources !== undefined ? { skillSources: [...skillSources] } : {}
       };
     } catch (error) {
@@ -11238,8 +11274,7 @@ class CloudEnvironmentSession extends RemoteClientSessionCore {
       this.removeExternalToolHandler = null;
       this.removeControlRequestHandler?.();
       this.removeControlRequestHandler = null;
-      this.mcpBridge?.close();
-      this.mcpBridge = null;
+      await this.closeMcpBridge();
       client.close();
       await this.cleanupManagedSandbox();
       await this.cleanupSessionRepositories(resolved.runtime.agent_id, resolved.runtime.conversation_id);
@@ -11292,13 +11327,22 @@ class CloudEnvironmentSession extends RemoteClientSessionCore {
     this.removeExternalToolHandler = null;
     this.removeControlRequestHandler?.();
     this.removeControlRequestHandler = null;
-    this.mcpBridge?.close();
-    this.mcpBridge = null;
+    this.mcpCleanup = this.closeMcpBridge();
     this.cleanupManagedSandbox();
     if (this.runtime?.agent_id) {
       this.cleanupSessionRepositories(this.runtime.agent_id, this.runtime.conversation_id);
     }
   }
+  async onCoreDisposed() {
+    await this.mcpCleanup;
+  }
+  closeMcpBridge() {
+    const bridge = this.mcpBridge;
+    this.mcpBridge = null;
+    for (const tool of bridge?.tools ?? [])
+      this.externalTools.delete(tool.name);
+    return bridge?.close() ?? Promise.resolve();
+  }
   async resolveRuntime() {
     let agentId = this.cloudMode.agentId;
     let conversationId = this.cloudMode.conversationId;
@@ -11819,8 +11863,36 @@ function validateReasoningEffort(value) {
     throw new Error(`Invalid reasoningEffort '${String(value)}'. Valid values: ${VALID_REASONING_EFFORTS.join(", ")}`);
   }
 }
+function validateMcpServers(servers) {
+  if (servers === undefined)
+    return;
+  if (!servers || typeof servers !== "object" || Array.isArray(servers)) {
+    throw new Error("Invalid mcpServers. Expected an object keyed by server name.");
+  }
+  for (const [name, config] of Object.entries(servers)) {
+    if (name.length === 0) {
+      throw new Error("Invalid mcpServers. Server names must be non-empty.");
+    }
+    if (!config || typeof config !== "object" || Array.isArray(config)) {
+      throw new Error(`Invalid MCP server '${name}'. Expected a configuration object.`);
+    }
+    if (config.type === "http" || config.type === "sse") {
+      if (typeof config.url !== "string" || config.url.length === 0) {
+        throw new Error(`Invalid MCP server '${name}'. Expected a non-empty url.`);
+      }
+      continue;
+    }
+    if (config.type !== undefined && config.type !== "stdio") {
+      throw new Error(`Invalid MCP server '${name}' type '${String(config.type)}'. Valid values: stdio, http, sse.`);
+    }
+    if (typeof config.command !== "string" || config.command.length === 0) {
+      throw new Error(`Invalid MCP server '${name}'. Expected a non-empty command.`);
+    }
+  }
+}
 function validateCreateSessionOptions(options) {
   validateSkillSources(options.skillSources);
+  validateMcpServers(options.mcpServers);
   validateReasoningEffort(options.reasoningEffort);
   validateDreamingOptions(options.dreaming);
   validateApprovalRecoveryOptions(options);
@@ -12249,4 +12321,4 @@ export {
   CloudManagedSandboxExpiredError
 };
 
-//# debugId=6301765BD48499AE64756E2164756E21
+//# debugId=713A28441574387164756E2164756E21