Tools: Model Context Protocol (mcp)

Lectic can act as a client for servers that implement the Model Context Protocol (MCP). This allows you to connect your LLM to a vast and growing ecosystem of pre-built tools and services.

What is MCP?

MCP is a standard protocol for connecting LLMs to external tools and data sources. Instead of writing custom integrations for every service, you can use any MCP-compatible server. Servers exist for GitHub, databases, file systems, web browsers, and much more.

The protocol handles the details of how tools describe themselves and how results are returned. Lectic speaks MCP, so you can drop in any compatible server and the LLM can use its tools immediately.

You can find lists of available servers here:

• Official MCP Server List
• Awesome MCP Servers

Configuration

Note: The snippets below show only the tool definition. They assume you have an interlocutor with a valid prompt and model configuration. See Getting Started for a full header example.

You can connect to an MCP server in three ways: by running a local server as a command, or by connecting to a remote server over WebSockets or SSE.

Local MCP Server (mcp_command)

This is the most common way to run an MCP server. You provide the command to start the server, and Lectic manages its lifecycle.

tools:
  - name: brave
    mcp_command: npx
    args:
      - "-y"
      - "@modelcontextprotocol/server-brave-search"
    env:
      BRAVE_API_KEY: "your_key_here"
    roots:
      - /home/user/research-docs/

Local MCP servers are started on demand for the active interlocutor and managed by Lectic for the duration of the session.

Remote MCP Servers

You can also connect to running MCP servers.

• mcp_ws: The URL for a remote server using a WebSocket connection.
• mcp_shttp: The URL for a remote server using Streamable HTTP.

For example:

tools:
  - name: documentation_search 
    mcp_shttp: https://mcp.context7.com/mcp

Authentication for Streamable HTTP

The mcp_shttp transport supports both custom headers and dynamic OAuth 2.0.

Custom headers can be provided using the headers key. Header values support file: and exec: sources, which is useful for securely loading tokens or computing authentication headers on the fly.

tools:
  - name: github_mcp
    mcp_shttp: https://api.githubcopilot.com/mcp
    headers:
      Authorization: exec:bash -c 'echo "Bearer $(pass github_token)"'

If a server requires OAuth 2.0 and supports the MCP OAuth flow, Lectic will automatically handle the authorization process. When an unauthorized request is made, Lectic will open your default browser to complete the login, and then securely persist the resulting tokens in your data directory.

Server Resources and Content References

If you give an MCP tool a name (e.g., name: brave), you can access any resources it provides using a special content reference syntax. The scheme is the server’s name plus the resource type.

For example, to access a repo resource from a server named github: [README](github+repo://gleachkr/Lectic/contents/README.md)

The LLM is also given a tool to list the available resources from the server.

Blacklisting and whitelisting server tools

You can hide specific tools that a server exposes by listing their names under exclude.

tools:
  - name: github
    mcp_ws: wss://example.org/mcp
    exclude:
      - dangerous_tool
      - low_value_tool

You can also limit access to a specific set of tools that a server exposes by listing their names under only.

tools:
  - name: github
    mcp_ws: wss://example.org/mcp
    only:
      - safe_tool
      - high_value_tool

If you specify both options at once, you’ll get exactly the tools from the only list that aren’t also excluded.

Safety and trust

Warning

While powerful, the MCP protocol carries significant security risks. Treat MCP integration as a high-trust capability. Never connect to untrusted servers; a malicious server could exfiltrate data or perform unwanted actions. Lectic’s safety mechanisms reduce mistakes from a well‑behaved LLM, not attacks from a hostile server.

Confirmation via hooks

Just like with the exec tool, you can use the tool_use_pre hook to implement confirmation dialogs or logic. See Hooks for examples.

Sandboxing (sandbox)

For local mcp_command tools, you can specify a sandbox command. This command will be used to launch the MCP server process in a controlled and isolated environment, limiting its access to your system. Arguments are supported (e.g. sandbox: wrapper.sh --strict).

See the documentation for the Exec Tool for more details on how sandboxing scripts work, and the Custom Sandboxing recipe for examples.

You can also set a default sandbox at the top level (sandbox) or on the interlocutor object. If set, it applies to all local mcp_command tools that don’t specify their own. Tool-level sandbox wins over both defaults.