@letta-ai/letta-agent-sdk 0.5.5 → 0.5.7

package/README.md

@@ -10,14 +10,6 @@ Build applications with stateful agents powered by the [Letta agent harness](htt
 npm install @letta-ai/letta-agent-sdk
 ```
 
-The `0.4.x` SDK line requires the matching single-socket
-`@letta-ai/letta-code` app-server release. Release `letta-code` first, then
-replace the SDK's package dependency with that published version before
-publishing `0.4.0`; the development branch intentionally does not name an
-unpublished package version.
-
-Local execution requires Node.js 22.19 or newer.
-
 ## Quick start
 
 ```ts
@@ -127,6 +119,49 @@ await using session = client.createSession(agentId, {
 });
 ```
 
+Local execution (embedded Letta Code harness / app server) requires Node.js 22.19 or newer.
+
+### MCP tools
+
+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: {
+    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"],
+});
+```
+
+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
 
 Cloud sessions can clone up to 10 GitHub repositories into the managed

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

@@ -66,12 +66,16 @@ export declare class AppServerSession extends RemoteClientSessionCore {
     private readonly remoteOptions;
     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

@@ -8615,6 +8615,35 @@ function buildCanUseToolContext(request, requestId) {
   return context;
 }
 
+// src/mcp-runtime.ts
+var connector = null;
+async function connectMcpServers(servers, options = {}) {
+  if (!servers || Object.keys(servers).length === 0) {
+    return { tools: [], close: async () => {
+      return;
+    } };
+  }
+  if (!connector) {
+    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([
   "error",
@@ -9822,6 +9851,7 @@ class RemoteClientSessionCore {
   }
   async[Symbol.asyncDispose]() {
     this.close();
+    await this.onCoreDisposed();
   }
   async changeDeviceState(updates) {
     if (!this.initialized) {
@@ -9863,6 +9893,7 @@ class RemoteClientSessionCore {
   async afterRuntimeInitialized() {}
   async beforeTurn() {}
   onCoreClose() {}
+  async onCoreDisposed() {}
   currentOptions() {
     return this.mode.options;
   }
@@ -10112,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 } : {}
     };
   };
 }
@@ -10403,6 +10435,8 @@ class AppServerSession extends RemoteClientSessionCore {
   remoteOptions;
   ownedConnection = null;
   externalTools = new Map;
+  mcpBridge = null;
+  mcpCleanup = Promise.resolve();
   removeExternalToolHandler = null;
   removeControlRequestHandler = null;
   constructor(remoteOptions, mode) {
@@ -10422,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,
@@ -10429,6 +10464,14 @@ class AppServerSession extends RemoteClientSessionCore {
       ...this.remoteOptions.WebSocket ? { WebSocket: this.remoteOptions.WebSocket } : {},
       ...this.remoteOptions.requestTimeoutMs !== undefined ? { requestTimeoutMs: this.remoteOptions.requestTimeoutMs } : {}
     }));
+    const options = this.currentOptions();
+    this.mcpBridge = await connectMcpServers("mcpServers" in options ? options.mcpServers : undefined, {
+      cwd: options.cwd,
+      reservedToolNames: this.externalTools.keys()
+    });
+    for (const tool of this.mcpBridge.tools) {
+      this.externalTools.set(tool.name, tool);
+    }
     this.removeControlRequestHandler = registerAppServerControlRequestHandler({
       client,
       getRuntime: () => this.runtime,
@@ -10445,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) {
@@ -10458,6 +10504,7 @@ class AppServerSession extends RemoteClientSessionCore {
       this.removeExternalToolHandler = null;
       this.removeControlRequestHandler?.();
       this.removeControlRequestHandler = null;
+      await this.closeMcpBridge();
       client.close();
       throw error;
     }
@@ -10467,9 +10514,20 @@ class AppServerSession extends RemoteClientSessionCore {
     this.removeExternalToolHandler = null;
     this.removeControlRequestHandler?.();
     this.removeControlRequestHandler = 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;
@@ -10504,7 +10562,7 @@ class AppServerSession extends RemoteClientSessionCore {
     if (options.skillSources !== undefined) {
       command.skill_sources = [...new Set(options.skillSources)];
     }
-    const groups = externalToolGroups(options.tools);
+    const groups = externalToolGroups([...this.externalTools.values()]);
     if (groups)
       command.external_tools = groups;
     if (this.mode.kind === "create-agent") {
@@ -11124,6 +11182,8 @@ class CloudEnvironmentSession extends RemoteClientSessionCore {
   removeExternalToolHandler = null;
   removeControlRequestHandler = null;
   externalTools = new Map;
+  mcpBridge = null;
+  mcpCleanup = Promise.resolve();
   managedSandbox = null;
   sandboxRefreshTimer = null;
   sandboxRefreshInFlight = null;
@@ -11145,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);
@@ -11171,6 +11232,14 @@ class CloudEnvironmentSession extends RemoteClientSessionCore {
       }),
       requestTimeoutMs: this.cloudOptions.requestTimeoutMs ?? DEFAULT_TURN_TIMEOUT_MS
     }));
+    const options = this.currentOptions();
+    this.mcpBridge = await connectMcpServers("mcpServers" in options ? options.mcpServers : undefined, {
+      cwd: options.cwd,
+      reservedToolNames: this.externalTools.keys()
+    });
+    for (const tool of this.mcpBridge.tools) {
+      this.externalTools.set(tool.name, tool);
+    }
     this.removeControlRequestHandler = registerAppServerControlRequestHandler({
       client,
       getRuntime: () => this.runtime,
@@ -11187,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) {
@@ -11202,6 +11274,7 @@ class CloudEnvironmentSession extends RemoteClientSessionCore {
       this.removeExternalToolHandler = null;
       this.removeControlRequestHandler?.();
       this.removeControlRequestHandler = null;
+      await this.closeMcpBridge();
       client.close();
       await this.cleanupManagedSandbox();
       await this.cleanupSessionRepositories(resolved.runtime.agent_id, resolved.runtime.conversation_id);
@@ -11228,7 +11301,7 @@ class CloudEnvironmentSession extends RemoteClientSessionCore {
     if (options.skillSources !== undefined) {
       command.skill_sources = [...new Set(options.skillSources)];
     }
-    const groups = externalToolGroups(options.tools);
+    const groups = externalToolGroups([...this.externalTools.values()]);
     if (groups)
       command.external_tools = groups;
     return await client.runtimeStart(command);
@@ -11254,11 +11327,22 @@ class CloudEnvironmentSession extends RemoteClientSessionCore {
     this.removeExternalToolHandler = null;
     this.removeControlRequestHandler?.();
     this.removeControlRequestHandler = 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;
@@ -11779,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);
@@ -12209,4 +12321,4 @@ export {
   CloudManagedSandboxExpiredError
 };
 
-//# debugId=8B8DDE1B1EDE2B4764756E2164756E21
+//# debugId=713A28441574387164756E2164756E21