Connecting Letta to remote MCP servers

Remote MCP servers work with both Letta Cloud and self-hosted deployments. Streamable HTTP is recommended for new integrations; SSE is deprecated but supported for legacy compatibility.

Streamable HTTP

Streamable HTTP is the recommended transport with support for MCP servers that use Bearer authorization, API keys, or OAuth 2.1. Letta also supports passing in custom headers for additional configuration.

ADE: Tool Manager → Add MCP Server → Streamable HTTP

Agent Id Header

When Letta makes tool calls to an MCP server, it includes the following in the HTTP request header:

x-agent-id: The ID of the agent making the tool call

If you’re implementing your own MCP server, this can be used to make requests against your Letta Agent via our API/SDK.

Agent Scoped Variables

Letta recognizes templated variables in the custom header and auth token fields to allow for agent-scoped parameters defined in your tool variables:

For example, {{ AGENT_API_KEY }} will use the AGENT_API_KEY tool variable if available.
To provide a default value, {{ AGENT_API_KEY | api_key }} will fallback to api_key if AGENT_API_KEY is not set.
This is supported in the ADE as well when configuring API key/access tokens and custom headers.

TypeScript
Python

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

const client = new Letta({ apiKey: process.env.LETTA_API_KEY });

// Connect a Streamable HTTP server with Bearer token auth
const streamableServer = await client.mcpServers.create({
  server_name: "my-server",
  config: {
    mcp_server_type: "streamable_http",
    server_url: "https://mcp-server.example.com/mcp",
    auth_header: "Authorization",
    auth_token: "Bearer your-token", // Include "Bearer " prefix
    custom_headers: {
      "X-API-Version": "v1", // Additional custom headers
    },
  },
});

// Example with templated variables for agent-scoped authentication
const agentScopedServer = await client.mcpServers.create({
  server_name: "user-specific-server",
  config: {
    mcp_server_type: "streamable_http",
    server_url: "https://api.example.com/mcp",
    auth_header: "Authorization",
    auth_token: "Bearer {{AGENT_API_KEY | api_key}}", // Agent-specific API key
    custom_headers: {
      "X-User-ID": "{{AGENT_API_KEY | user_id}}", // Agent-specific user ID
      "X-API-Version": "v2",
    },
  },
});

from letta_client import Letta
import os

client = Letta(api_key=os.getenv("LETTA_API_KEY"))

# Connect a Streamable HTTP server with Bearer token auth
streamable_server = client.mcp_servers.create(
    server_name="my-server",
    config={
        "mcp_server_type": "streamable_http",
        "server_url": "https://mcp-server.example.com/mcp",
        "auth_header": "Authorization",
        "auth_token": "Bearer your-token",  # Include "Bearer " prefix
        "custom_headers": {"X-API-Version": "v1"}  # Additional custom headers
    }
)

# Example with templated variables for agent-scoped authentication
agent_scoped_server = client.mcp_servers.create(
    server_name="user-specific-server",
    config={
        "mcp_server_type": "streamable_http",
        "server_url": "https://api.example.com/mcp",
        "auth_header": "Authorization",
        "auth_token": "Bearer {{AGENT_API_KEY | api_key}}",  # Agent-specific API key
        "custom_headers": {
            "X-User-ID": "{{AGENT_API_KEY | user_id}}",  # Agent-specific user ID
            "X-API-Version": "v2"
        }
    }
)

SSE (Deprecated)

For legacy MCP servers that only support SSE.

ADE: Tool Manager → Add MCP Server → SSE