Tool UseModel Context Protocol

Connecting Letta to Remote MCP Servers

Using Streamable HTTP and SSE transports

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.
1import { LettaClient, Letta } from '@letta-ai/letta-client';
2
3const client = new LettaClient({ token: "LETTA_API_KEY" });
4
5// Connect a Streamable HTTP server with Bearer token auth
6const streamableConfig: Letta.StreamableHttpServerConfig = {
7    serverName: "my-server",
8    type: Letta.McpServerType.StreamableHttp,
9    serverUrl: "https://mcp-server.example.com/mcp",
10    authHeader: "Authorization",
11    authToken: "Bearer your-token",  // Include "Bearer " prefix
12    customHeaders: {
13        "X-API-Version": "v1"  // Additional custom headers
14    }
15};
16
17await client.tools.addMcpServer(streamableConfig);
18
19// Example with templated variables for agent-scoped authentication
20const agentScopedConfig: Letta.StreamableHttpServerConfig = {
21    serverName: "user-specific-server",
22    type: Letta.McpServerType.StreamableHttp,
23    serverUrl: "https://api.example.com/mcp",
24    authHeader: "Authorization",
25    authToken: "Bearer {{AGENT_API_KEY | api_key}}",  // Agent-specific API key
26    customHeaders: {
27        "X-User-ID": "{{AGENT_API_KEY | user_id}}",  // Agent-specific user ID
28        "X-API-Version": "v2"
29    }
30};
31
32await client.tools.addMcpServer(agentScopedConfig);

SSE (Deprecated)

SSE is deprecated. Use Streamable HTTP for new integrations if available.

For legacy MCP servers that only support SSE.

ADE: Tool Manager → Add MCP Server → SSE

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.
1import { LettaClient, Letta } from '@letta-ai/letta-client';
2
3const client = new LettaClient({ token: "LETTA_API_KEY" });
4
5// Connect a SSE server (legacy)
6const sseConfig: Letta.SseServerConfig = {
7    serverName: "legacy-server",
8    type: Letta.McpServerType.Sse,
9    serverUrl: "https://legacy-mcp.example.com/sse",
10    authHeader: "Authorization",
11    authToken: "Bearer optional-token"  // Include "Bearer " prefix
12    customHeaders: {
13        "X-User-ID": "{{AGENT_API_KEY | user_id}}",  // Agent-specific user ID
14        "X-API-Version": "v2"
15    }
16};
17
18await client.tools.addMcpServer(sseConfig);

Using MCP Tools

ADE: Agent → Tools → Select MCP tools

1import { LettaClient } from '@letta-ai/letta-client'
2
3const client = new LettaClient({ token: "LETTA_API_KEY" });
4
5// List tools from an MCP server
6const tools = await client.tools.listMcpToolsByServer("weather-server");
7
8// Add a specific tool from the MCP server
9const tool = await client.tools.addMcpTool("weather-server", "get_weather");
10
11// Create agent with MCP tool
12const agentState = await client.agents.create({
13    model: "openai/gpt-4o-mini",
14    embedding: "openai/text-embedding-3-small",
15    toolIds: [tool.id]
16});
17
18// Use the agent with MCP tools
19const response = await client.agents.messages.create(agentState.id, {
20    messages: [
21        {
22            role: "user",
23            content: "Use the weather tool to check the forecast"
24        }
25    ]
26});