using-mcp-tools

name	using-mcp-tools
description	Reference for the `letta mcp` CLI, which finds and invokes MCP tools available to this agent. A system reminder already lists your connected MCP servers and the basic search/schema/call commands; invoke this skill when you need more — browsing a server's tools, passing large or file-based arguments, tuning search, or troubleshooting missing servers, tools, and errors.

Using MCP tools

letta mcp gives the agent one unified view of every MCP server it can reach: servers connected to the agent in Letta Cloud and servers configured locally on this machine. It works from any surface where the agent runs — cloud sandboxes (chat.letta.com), Letta Desktop, and terminals. All output is JSON.

Commands

letta mcp list                                # servers: [{name, transport}]
letta mcp get <server>                        # one server's connection configuration (credentials redacted)
letta mcp tools [server]                      # tool names + descriptions only
letta mcp tools [server] --full               # ...including every tool's complete schema
letta mcp schema <tool-name>                  # one tool's complete schema
letta mcp search <query> [--mode] [--limit]   # ranked tool schemas: [{tool, rank, score}]
letta mcp call <tool-name> [--args | --args-file]  # run a tool, print a CallToolResult

Every command accepts --agent <id>, defaulting to LETTA_AGENT_ID/AGENT_ID — do not pass it unless targeting another agent.

Search options

• --mode <hybrid|vector|fts> — default hybrid. vector uses server-side embeddings and covers only cloud-connected servers; fts and hybrid also rank local tools lexically. Agents on a local backend cannot use vector.
• --limit <n> — result count, 1-100 (default 5).
• Rank order is meaningful; absolute scores are not comparable across queries. When even the top results look unrelated to the query, no relevant tool likely exists — do not force the best-ranked one.

Call arguments and results

• --args '<json>' — inline JSON object.
• --args-file <path> — read the JSON object from a file; --args-file - reads stdin. Use these for large or shell-quoting-hostile payloads.
• Output is an MCP CallToolResult: content (array of typed blocks), optional structuredContent, and isError.
• Exit codes: 0 success, 1 CLI/usage error (JSON on stderr: {error: {code, message, hint?}}), 2 the tool ran and returned an error result — read content for the server's message, fix the arguments, and retry.
• Summarize relevant results instead of pasting large raw payloads.

Troubleshooting

• list empty → no MCP servers are available. Ask the user to connect one on the Letta Cloud MCP servers page or configure a local one in the Letta Code app.
• Cloud server with no tools (or 0 tools in the reminder) → tools were never synced. Ask the user to resync it from the MCP servers page; the CLI has no refresh action.
• unauthorized or another auth error on call → the server's stored credentials are missing or stale (tools can still list from previously synced rows). Ask the user to re-authenticate the server: cloud servers on the MCP servers page, local OAuth servers by connecting once in the Letta Code app — this CLI is non-interactive and only reuses persisted credentials.
• ambiguous_server_name → two servers share a name; the error hint explains how to disambiguate.
• Duplicate tool names across servers get a numeric suffix (_2); the printed name is always the callable one.