MCP remote execution

Model Context Protocol (MCP) tools execute on external MCP servers, not in Letta’s sandbox or your application. This allows agents to access external services and APIs through a standardized protocol.

How it works

When an agent calls an MCP tool, the execution flow is:

1. Agent decision: The agent decides to call an MCP tool with specific arguments.
2. Request forwarding: The Letta server forwards the tool call to the MCP server.
3. Remote execution: The MCP server executes the tool in its environment.
4. Result return: The MCP server returns the result to Letta.
5. Agent continuation: The agent receives the result and continues processing.

flowchart LR
    Agent[Letta agent] -->|Tool call| Letta[Letta server]
    Letta -->|Forward request| MCP[MCP server]
    MCP -->|Execute rool| Tool[External service]
    Tool -->|Result| MCP
    MCP -->|Return result| Letta
    Letta -->|Continue| Agent

Execution environment

• Controlled by: The MCP server (external)
• Permissions: Defined by the MCP server implementation
• Dependencies: Managed by MCP server
• Security: The MCP server’s responsibility
• State: The MCP server can maintain persistent state

Unlike custom tools that run in Letta’s sandbox or client-side tools that run in your application, MCP tools are completely managed by the external MCP server.

When to use MCP execution

MCP execution is ideal for integrating external service integration, centralized tool management, and server-side logic.

External service integration

Connect to services that provide MCP servers:

• GitHub API (repositories, issues, pull requests)
• Slack API (channels, messages, workspace data)
• Database services (PostgreSQL, MySQL)
• Cloud storage (S3, Google Drive)
• Third-party APIs with MCP implementations

Centralized tool management

With MCP remote execution, you can:

• Share tools across multiple agents and projects
• Update tools without redeploying agents
• Maintain state in the MCP server between calls
• Control access to sensitive services centrally

Server-side logic

The server-side logic includes:

• Complex business logic that shouldn’t run in the agent sandbox
• Operations requiring persistent connections (databases, message queues)
• Tools that need access to server-side resources
• Integrations with existing backend services

Setting up MCP tools

For detailed setup instructions, see the MCP documentation.

• MCP overview: Discover the Model Context Protocol.
• MCP setup: Configure MCP servers with Letta.
• Remote MCP servers: Connect to external MCP servers.
• Local MCP servers: Run MCP servers locally.

MCP tools are automatically discovered and registered when you connect an MCP server to Letta. The server defines which tools are available and how they are executed.

Example: GitHub MCP server

Here’s how an MCP tool works in practice with a GitHub MCP server:

1. Connect to the MCP server: Configure Letta to connect to a GitHub MCP server.
2. Automatically discover tools: Letta discovers available tools (for example, create_issue and list_repos).
3. Attach tools to the agent: Add the MCP tools to your agent.
4. The agent uses the tool: The agent calls create_issue with repository and issue details.
5. The MCP server executes: The GitHub MCP server creates the issue via the GitHub API.
6. The result returns: The agent receives confirmation of the issue creation.

The agent doesn’t need to know about the GitHub API authentication, rate limiting, or API details. The MCP server handles everything.

Comparison with other execution modes

Sandbox execution (custom tools)

Feature	MCP remote	Sandbox
Execution location	External MCP server	Letta sandbox (E2B/local)
Tool definition	MCP server provides	You define in code
State management	MCP server can maintain	Stateless per execution
External API access	MCP server handles	Limited from sandbox
Setup complexity	MCP server setup required	Direct tool creation

Use MCP tools when integrating existing services with MCP implementations. Use sandbox execution when writing custom logic specific to your agent.

Client-side execution

Feature	MCP remote	Client-side
Execution location	External MCP server	Your application
Control	MCP server managed	You manage completely
Local resources	No	Yes
API credentials	MCP server stores	Your app manages
Approval flow	Optional	Required (HITL)

Use MCP tools when you want centralized tool management and external service integration. Use client-side tools when you need access to local resources or full control over execution.

Built-in tools

Feature	MCP remote	Built-in
Execution location	External MCP server	Letta server (privileged)
Modifiable	Via MCP server	No
Service scope	External services	System operations
Examples	GitHub, Slack	web_search, run_code

Use MCP tools for external service integrations. Use built-in tools for system operations, like web search and code execution.

Security considerations

When using MCP remote execution:

• The MCP server handles authentication: The credentials are stored on the MCP server, not in Letta.
• Network security: Ensure a secure connection between Letta and the MCP server.
• Trust the MCP server: The server has full control over the tool execution.
• Rate limiting: The MCP server may implement rate limits.
• Access control: The MCP server manages permissions for external services.

Related

• MCP documentation: Read the complete MCP integration guide.
• Tool execution overview: Compare all execution modes.
• Custom tools: Create tools for the Letta sandbox.
• Client-side tools: Execute tools locally.