# Record
**Author:** @cameron.stream (`did:plc:gfrmhdmjvxn2sjedzboeudef`)

## `knowledge-skills-mcp-mods-and-agent-sdk`
**Collection:** `site.standard.document`
**AT URI:** `at://did:plc:gfrmhdmjvxn2sjedzboeudef/site.standard.document/knowledge-skills-mcp-mods-and-agent-sdk`

**Title:** Skills, MCP, Mods, and the Agent SDK
**Published:** Thu, 03 Sep 2026 10:15:11 GMT
**Updated:** Thu, 03 Sep 2026 10:13:30 GMT
**Description:** A map of four Letta extension surfaces and the layer of agency each one changes.
**Publication:** `at://did:plc:gfrmhdmjvxn2sjedzboeudef/site.standard.publication/3mr4py6clps2f`
**Path:** /skills-mcp-mods-and-agent-sdk
**Tags:** knowledge, map, AI agents, Letta, developer tools

**Content:**
```json
{
  "text": "Letta exposes several ways to extend an agent, but each one owns a different layer of the system. [Skills](https://docs.letta.com/configuration/skills) shape reusable procedure, [MCP](https://docs.letta.com/agent-sdk/mcp) adds external capabilities to a session, [mods](https://docs.letta.com/configuration/mods) alter the trusted Letta Code process, and the [Agent SDK](https://docs.letta.com/agent-sdk) embeds a stateful agent in an application.\n\nThis map complements [building with Letta agents](https://cameron.stream/knowledge/building-with-letta-agents), [learning from documentation](https://cameron.stream/knowledge/learning-from-documentation-with-letta-agent-sdk), and [choosing an agent topology](https://cameron.stream/knowledge/choosing-an-agent-topology). Its narrower question is where a new behavior should live.\n\n## Choose by owner, then by depth\n\nStart 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:\n\n1. Does the agent need a reusable procedure, reference material, or bundled script for a specialized task? Start with a skill.\n2. Does one application session need tools supplied by an external server? Configure MCP through the Agent SDK host.\n3. Must the local Letta Code process change how commands, turns, tools, permissions, providers, or interface elements behave? Write a mod.\n4. 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.\n\nThe 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.\n\n## Skills package task knowledge\n\nA 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.\n\nLetta 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.\n\nThose 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.\n\nThe 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.\n\n## MCP supplies session-scoped tools\n\nIn 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.\n\nBoth 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.\n\nThe 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.\n\nExecution 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.\n\nIn 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.\n\n## Mods change the trusted harness\n\nHere, 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.\n\nA 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.\n\nSome 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.\n\nA 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.\n\n## The Agent SDK makes the application the host\n\nLetta 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.\n\nThe 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.\n\nChoose 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.\n\n## Combine surfaces without confusing their owners\n\nThe 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.\n\nThe 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.\n\n## A compact selection test\n\n| Needed change | Smallest likely surface | Ownership test |\n| --- | --- | --- |\n| Preserve a migration or deployment procedure with a project | Project-scoped skill | The repository owns the instructions and supporting files. |\n| Preserve a workflow with one agent across projects and computers | Agent-scoped skill | The agent owns the procedure in its memory system. |\n| 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. |\n| Rewrite tool arguments or enforce a dynamic policy before execution | Mod | The local Letta Code process owns the intervention point. |\n| Build a custom frontend or coordinate multiple persistent agents | Agent SDK | The application owns sessions, users, orchestration, and presentation. |\n\nIf 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.\n\n## Sources\n\n- [Letta documentation overview](<https://docs.letta.com/>)\n- [Letta skills documentation](<https://docs.letta.com/configuration/skills>)\n- [Letta mods documentation](<https://docs.letta.com/configuration/mods>)\n- [Letta Agent SDK overview](<https://docs.letta.com/agent-sdk>)\n- [MCP and client tools in the Agent SDK](<https://docs.letta.com/agent-sdk/mcp>)",
  "$type": "site.standard.content.markdown",
  "version": "1.0"
}
```

---
*Fetched from https://enoki.us-east.host.bsky.network via `com.atproto.repo.getRecord`*