Serving tools via MCP

term-llm serve mcp exposes term-llm’s local tools to MCP clients over HTTP. For example, a cloud development box can run the server while a local term-llm instance—or another MCP client—uses its tools remotely.

Quick start#

# Expose all tools on localhost
term-llm serve mcp --tools all

# Expose just file reading and search
term-llm serve mcp --tools read_file,grep,glob

# Full power on a cloud dev box
term-llm serve mcp --tools all --host 0.0.0.0 --port 8080 \
  --write-dir /home/sam/project \
  --shell-allow "go *" --shell-allow "git *" --shell-allow "make *"

On startup the server prints the URL, auth token, and enabled tools:

MCP server listening on http://127.0.0.1:8080/mcp
auth token: abc123...
tools: edit_file, glob, grep, read_file, shell, web_search, write_file, ...

When binding to a wildcard address (0.0.0.0 or ::), the printed URL uses 127.0.0.1 for convenience. Remote clients should use the machine’s actual hostname or IP.

Connecting a client#

From another terminal (or machine), add the server as an MCP endpoint:

term-llm mcp add http://devbox:8080/mcp   # prompted for token
term-llm mcp info devbox                    # verify tools
term-llm mcp run devbox shell command="echo hello"
term-llm chat --mcp devbox "what files are in this directory?"

Via SSH tunnel (no --token needed since traffic stays on localhost):

ssh -L 8080:localhost:8080 devbox 'term-llm serve mcp --tools all'
term-llm mcp add http://localhost:8080/mcp

Available tools#

The --tools flag is required. Pass a comma-separated list of tool names, or all. Only the tools listed below are accepted. Internal tools like ask_user, spawn_agent, and view_image are not available in MCP server mode.

File & search#

Web#

web_search defaults to Exa MCP (search.provider: exa_mcp). read_url defaults to Jina Reader (search.fetch_provider: jina), or can use Exa MCP with search.fetch_provider: exa_mcp. If provider configuration is invalid, a warning is logged and the tool is skipped.

Image#

The all shorthand#

--tools all expands to: read_file, write_file, edit_file, shell, grep, glob, image_generate, web_search, read_url. Because that set contains path-capable tools, manage_workspace is registered alongside it automatically. The same happens for an explicit list such as read_file,grep; a shell/web-only list does not receive it.

Tools whose backing provider isn’t configured are skipped with a warning.

Flags#

Shell allow patterns are matched per command and shell word. A final standalone * allows remaining arguments. Within a word, * does not cross /; use ** to match recursive path segments. Compound commands are allowed only when every command is covered.

Set a persistent mode for this server without changing other serve surfaces:

serve:
  mcp:
    approval_mode: auto # prompt or auto; yolo is CLI-only

Edit format#

By default, the edit_file tool (find/replace) is exposed. If the connecting LLM handles unified diffs better, use --edit-format diff to swap it for the unified_diff tool instead. Only one edit tool is exposed at a time to avoid confusing the LLM.

# Default: find/replace edit tool
term-llm serve mcp --tools all

# Swap to unified diff edit tool
term-llm serve mcp --tools all --edit-format diff

Security#

• Auth: Bearer token authentication on every request (constant-time comparison). Token is auto-generated if not provided.
• Localhost by default: Binds to 127.0.0.1. You must explicitly pass --host 0.0.0.0 to accept remote connections.
• Transport security: The server uses plain HTTP. When exposing beyond localhost, use an SSH tunnel, VPN, or TLS-terminating reverse proxy to protect traffic in transit.
• Permissions: --read-dir, --write-dir, and --shell-allow restrict what the tools can access. The built-in mode is prompt. The MCP daemon CWD is not even a proposed workspace. If an explicit request/session workspace is supplied, it is only a pending primary proposal; this headless server has no human workspace-confirmation transport, so first file/path access inside it fails closed even in auto or yolo. Pre-configure deterministic file permissions instead. Additional manage_workspace grants are runtime-only here (there is no persisted conversation session) and never authorize shell commands.
• Auto: --approval auto asks Guardian to review supported unmatched shell and local file/path operations. Guardian must initialize before the server starts; denials and review errors return to the agent without prompting for that same action. If the 3-consecutive/20-total breaker suspends auto, the existing approval transport handles subsequent effective-prompt requests, but auto’s arbitrary-execution shell-pattern filter remains latched so broad rules cannot become implicit approvals. This feature does not add a web mode-cycle or explicit-resume control.
• No ask_user: The server runs non-interactively. Use deterministic permission flags, guardian-reviewed auto, or explicit yolo as appropriate.

Examples#

# Read-only file browser
term-llm serve mcp --tools read_file,grep,glob \
  --read-dir /var/log --read-dir /etc

# Development server with restricted shell
term-llm serve mcp --tools all \
  --host 0.0.0.0 \
  --write-dir ~/project \
  --shell-allow "go *" --shell-allow "git *" --shell-allow "make *"

# Guardian-reviewed unattended operation
term-llm serve mcp --tools all --approval auto

# CI/container use: explicitly bypass approvals
term-llm serve mcp --tools all --approval yolo

# Custom port and token
term-llm serve mcp --tools all --port 9090 --token my-secret-token

# Remote access via SSH tunnel (recommended over --host 0.0.0.0)
ssh -L 8080:localhost:8080 devbox 'term-llm serve mcp --tools all'