Letta exposes several ways to extend an agent, but each one owns a different layer of the system. Skills shape reusable procedure, MCP adds external capabilities to a session, mods alter the trusted Letta Code process, and the Agent SDK embeds a stateful agent in an application.
This map complements building with Letta agents, learning from documentation, and choosing an agent topology. Its narrower question is where a new behavior should live.
Choose by owner, then by depth
Start with the shallowest layer that can own the change without borrowing state or authority from a deeper one. As an engineering heuristic, ask these questions in order:
- Does the agent need a reusable procedure, reference material, or bundled script for a specialized task? Start with a skill.
- Does one application session need tools supplied by an external server? Configure MCP through the Agent SDK host.
- Must the local Letta Code process change how commands, turns, tools, permissions, providers, or interface elements behave? Write a mod.
- Does an application need to create or resume agents, orchestrate them, stream their output, or place a custom interface around them? Use the Agent SDK.
The order avoids granting process-level control to something that only needed instructions. It also keeps application credentials and connection lifecycles in the application when the agent itself does not need to retain them.
Skills package task knowledge
A skill is a directory of instructions and resources that the agent can load when relevant. Skills may include executable scripts, and those scripts can call an API, use an SDK, or connect to an MCP server. The scripts execute with tools available on the selected computer, API access remains subject to the agent's permissions, and credentials should be stored as secrets rather than placed inside the skill.
Letta registers skills from project, agent, computer, and built-in scopes. Project-scoped skills live with a particular project. Agent-scoped skills live in the agent's memory system and follow that agent between computers. Computer-scoped skills are shared by agents on one machine, while built-in skills ship with Letta Code.
Those scopes make skills useful for procedures whose ownership is already clear. A database migration workflow belongs naturally to the project performing the migration. A workflow specific to one agent can belong to that agent. A capability needed by every agent on a particular machine can be installed at computer scope.
The documentation therefore supports treating code inside a skill as part of a reusable workflow rather than as an automatic reason to modify the harness. The defining question is whether the extension teaches the agent how to perform work with its available tools. Because skills can contain executable code and prompts, Letta advises installing them only from trusted sources.
MCP supplies session-scoped tools
In the Agent SDK, client tools and MCP tools are both exposed through the application's Node.js process. Client tools are JavaScript functions supplied directly by the application. MCP tools are discovered from configured servers and proxied by the SDK host to those servers.
Both kinds are scoped to the SDK session and are not persisted on the agent. Their implementations, processes, credentials, and filesystem access belong to the application hosting that session. Different sessions connected to the same stateful agent may therefore use different MCP servers and credentials.
The SDK supports local stdio processes, Streamable HTTP, and legacy SSE servers. Connections begin during session initialization, and one unavailable server does not prevent healthy servers from connecting. Closing or asynchronously disposing the session closes its MCP connections and child processes.
Execution location is consequential. A stdio filesystem server sees the SDK host's filesystem, including when the agent itself is reached through Cloud or another remote deployment. Local executables and environment variables must also exist on that host. An allowedTools list acts as an availability filter across client, MCP, and built-in tools; if it is supplied, every tool the session should expose must be included.
In this map, MCP is best read as a session-level capability connection. That reading is limited to the documented Agent SDK integration. MCP requires the SDK's Node.js package entry point and is unavailable from the portable client entry point used by browser and React Native applications.
Mods change the trusted harness
Here, the trusted harness means the local Letta Code process in which a mod executes. Mods run as fully trusted code inside the local Letta Code process, with the same access as Letta Code itself. Files in the global mods directory load at startup and can be reloaded without restarting the process.
A mod can add commands, tools, event handling, permission policies, provider adapters, diagnostics, and terminal UI. Event handlers can intervene at particularly deep points: they can modify tool arguments before execution, replace tool results, inject or rewrite turn context, cancel a turn, or chain another turn. Dynamic permission policies can allow, ask about, or deny a tool call before it executes.
Some hooks apply only to local agents. Events around model requests and compaction do not fire for agents reached through the Letta API because inference and compaction occur server-side. Custom provider mods are local-only for the same reason.
A practical reading is to choose a mod when the requirement is expressed in harness terms: enforce a policy before tool execution, add a local slash command, alter turn handling, register a provider, or change terminal behavior. A broken individual mod is skipped and reported through diagnostics, and Letta Code can be started with mods disabled for a clean baseline. Those recovery mechanisms do not reduce the trust level of working mods, which retain process-level access.
The Agent SDK makes the application the host
Letta describes the Agent SDK as an interface for creating an agent once and resuming it from different sessions and computers. The agent retains its identity and long-term memory across conversations, models, and computers. The SDK is intended for multi-agent and multi-user applications, dynamic orchestration, and custom interfaces placed around a Letta agent.
The SDK presents managed, local, and self-hosted deployments through one interface. The application can create or resume an agent, open a session, send messages, and consume the resulting event stream. When that application supplies client tools or MCP servers, their execution remains in its Node.js process even if the agent runtime is remote.
Choose the SDK when the product itself owns the interaction: deciding which agent a user resumes, coordinating several agents, integrating an agent into an existing interface, or managing application-specific tools and credentials. These responsibilities belong to the host application rather than to a procedure loaded into the agent.
Combine surfaces without confusing their owners
The mechanisms can be composed. An application might resume an agent through the SDK, attach an MCP search server for that session, and let the agent load a skill describing the research procedure. A mod would enter the design only if the local Letta Code process also needed different turn, permission, tool, provider, or interface behavior. This is a design inference from the documented ownership and lifecycle of each mechanism, not a required Letta architecture.
The same word, tool, appears at several layers without making those layers interchangeable. A skill can run a script that reaches an API or MCP server. A mod can register a tool directly inside Letta Code. An SDK application can supply a JavaScript client tool or proxy tools discovered from an MCP server. The implementation, credentials, lifetime, and enforcement point identify the owner more reliably than the generic label.
A compact selection test
| Needed change | Smallest likely surface | Ownership test |
|---|---|---|
| Preserve a migration or deployment procedure with a project | Project-scoped skill | The repository owns the instructions and supporting files. |
| Preserve a workflow with one agent across projects and computers | Agent-scoped skill | The agent owns the procedure in its memory system. |
| Connect one SDK session to a stdio, HTTP, or SSE tool server | MCP through the Agent SDK | The host application owns the connection, credentials, and shutdown. |
| Rewrite tool arguments or enforce a dynamic policy before execution | Mod | The local Letta Code process owns the intervention point. |
| Build a custom frontend or coordinate multiple persistent agents | Agent SDK | The application owns sessions, users, orchestration, and presentation. |
If a requirement spans several rows, assign one owner to each responsibility instead of selecting the deepest mechanism by default. As a design inference, the SDK host can own MCP credentials and connection shutdown while a skill owns the procedure for deciding when and how to use the resulting tools. Whether that split suits a particular product remains an application decision.