MCP Remote Execution

MCP (Model Context Protocol) 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 - Agent decides to call an MCP tool with specific arguments
2. Request Forwarding - Letta server forwards the tool call to the MCP server
3. Remote Execution - MCP server executes the tool in its environment
4. Result Return - MCP server returns the result to Letta
5. Agent Continuation - 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 Tool| Tool[External Service]
    Tool -->|Result| MCP
    MCP -->|Return Result| Letta
    Letta -->|Continue| Agent

Execution Environment

• Controlled by: MCP server (external)
• Permissions: Defined by MCP server implementation
• Dependencies: Managed by MCP server
• Security: MCP server’s responsibility
• State: 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:

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

• 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

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

Setting Up MCP Tools

For detailed setup instructions, see the MCP documentation:

• MCP Overview - Introduction to 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 discovered and registered automatically when you connect an MCP server to Letta. The server defines what tools are available and how they execute.

Example: GitHub MCP Server

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

1. Connect MCP Server - Configure Letta to connect to a GitHub MCP server
2. Automatic Tool Discovery - Letta discovers available tools (e.g., create_issue, list_repos)
3. Attach to Agent - Add the MCP tools to your agent
4. Agent Uses Tool - Agent calls create_issue with repository and issue details
5. MCP Server Executes - GitHub MCP server creates the issue via GitHub API
6. Result Returns - Agent receives confirmation of issue creation

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

Comparison with Other Execution Modes

vs 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 when integrating existing services with MCP implementations. Use Sandbox when writing custom logic specific to your agent.

vs 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 when you want centralized tool management and external service integration. Use Client-Side when you need access to local resources or full control over execution.

vs 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 for external service integrations. Use Built-in for system operations like web search and code execution.

Security Considerations

When using MCP remote execution:

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

Related

• MCP Documentation - Complete MCP integration guide
• Tool Execution Overview - Compare all execution modes
• Custom Tools - Create tools for Letta sandbox
• Client-Side Tools - Execute tools locally