Connecting Letta to a stdio MCP Server

If you’re using Docker to run Letta, local MCP servers (“command” or “stdio” servers) are not natively supported. See workarounds below, or use a remote MCP server.

The primary way to use MCP is to install an MCP server locally - see the MCP example server GitHub repo for a list of example MCP servers.

When you run an MCP server locally, the MCP client will read the instructions on how to launch the server (the command to run) the MCP config file, then launch the server in a subprocess - so technically the client is running the server.

Connecting local MCP servers to a Letta server in Docker

Local MCP servers pose an issue for Docker - since the MCP client (Letta) will attempt to start the MCP server using the command specified in the config, and because the Letta server is running inside of Docker, that means that the config file needs to specify a command that can be run inside of Docker.

There are three ways to solve this problem (in order of increasing difficulty):

  1. Use Letta Desktop. Letta Desktop runs a Letta server locally (not inside of Docker), so it will be able to run the command specified in the MCP config file to start the MCP server.
  2. Don’t use a local MCP server, instead use an MCP server that uses the SSE protocol (see instructions below on conecting Letta to a remote MCP server).
  3. Run an MCP SSE proxy to turn your local MCP server into a remote one. This example repo shows you how to run an MCP proxy to turn a local MCP server into a remote / SSE MCP server. If you follow this route, you will need to make sure you expose to appropriate ports during docker run to enable the Letta server to reach the MCP server URL.
  4. Install the MCP server inside the Docker container (e.g. at run-time via docker exec). If you install the MCP server inside the Docker container, the MCP client inside the Letta server will be able to execute the command specified in the config file. However, we don’t recommend this approach since the MCP server will need to be reinstalled on each restart.

Example: connecting to the Perplexity MCP server

Perplexity (the AI search company) has an official MCP server on GitHub that enables agents to use Perplexity to search the web.

To set their MCP server up with Letta, we first need to install the Perplexity MCP server locally. This requires a few steps (see their README for the full instructions):

  1. Clone the Perplexity MCP repo
  2. Install it with npm install
  3. Get a Sonar API key
  4. Build the MCP server Docker image

Once we’ve installed the Perplexity MCP server, we need to modify our ~/.letta/mcp_config.json file so that the Letta server will attempt to connect to it on startup:

1{
2 "mcpServers": {
3 "perplexity-ask": {
4 "command": "docker",
5 "args": [
6 "run",
7 "-i",
8 "--rm",
9 "-e",
10 "PERPLEXITY_API_KEY",
11 "mcp/perplexity-ask"
12 ],
13 "env": {
14 "PERPLEXITY_API_KEY": "YOUR_API_KEY_HERE"
15 }
16 }
17 }
18}

The format of the JSON is taken directly from the Perplexity MCP server’s README (it’s the same as setting up the MCP server for use with Claude Desktop). The contents of the config tell the MCP client (Letta) how to start the MCP server (using the command, args, and env).

This example will not work if you are using Docker to run Letta, since the command to run the MCP server (stored in the config) will not work from within the Docker container.

Once you start your Letta server, the Letta server will read the MCP config file and attempt to start then connect to the MCP server. If the connection is successful, the Letta server will then request a list of tools from the MCP server.

Note that you do not have to start the MCP server separately from the Letta server - because the Letta server is an MCP client, it will automatically start the server using the provided command and args. This is different from a “remote (SSE) MCP server”, where the MCP client assumes the server is already running (see below).