Connecting Letta to local MCP servers

stdio transport launches MCP servers as local subprocesses, ideal for development and testing. Local (stdio) MCP servers can be useful for local development, testing, and situations where the MCP server you want to use is only available via stdio.

Setup

ADE: Tool Manager → Add MCP Server → stdio → specify command and args

TypeScript
Python

import { Letta } from "@letta-ai/letta-client";

// Self-hosted only
const client = new Letta({
  baseUrl: "http://localhost:8283",
});

// Connect a stdio server (npx example - works in Docker!)
const stdioServer = await client.mcpServers.create({
  server_name: "github-server",
  config: {
    mcp_server_type: "stdio",
    command: "npx",
    args: ["-y", "@modelcontextprotocol/server-github"],
    env: { GITHUB_PERSONAL_ACCESS_TOKEN: "your-token" },
  },
});

// List available tools from this server
const tools = await client.mcpServers.tools.list(stdioServer.id);
console.log(`Found ${tools.length} tools from github-server`);

from letta_client import Letta

# Self-hosted only
client = Letta(base_url="http://localhost:8283")

# Connect a stdio server (npx example - works in Docker!)
stdio_server = client.mcp_servers.create(
    server_name="github-server",
    config={
        "mcp_server_type": "stdio",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-github"],
        "env": {"GITHUB_PERSONAL_ACCESS_TOKEN": "your-token"},
    }
)

# List available tools from this server
tools = client.mcp_servers.tools.list(stdio_server.id)
print(f"Found {len(tools)} tools from github-server")

Docker Support

Letta’s Docker image includes npx, so npm-based MCP servers work out of the box. Custom Python scripts or missing dependencies require workarounds.

Works in Docker: npx servers from the official MCP repository
Challenging: Custom scripts, local file paths, missing system dependencies
Alternatives: Use remote servers or mcp-proxy

Troubleshooting

Server won’t start: Check command path, dependencies, environment variables
Connection fails: Review Letta logs, test command manually
Tools missing: Verify MCP protocol implementation and tool registration