Guide

MCP servers

Larik connects to Model Context Protocol servers over stdio, streamable HTTP, or SSE. It reads servers from mcp_servers in any Larik settings file, and from a project .mcp.json in the common format, so configs shared with other tools work unchanged:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": { "Authorization": "Bearer ${GITHUB_TOKEN}" }
    },
    "fs": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "${HOME}/notes"]
    }
  }
}

• Server tools appear as mcp__<server>__<tool>. In rules, mcp__github covers every tool on that server.
• ${VAR} and ${VAR:-default} are expanded in the command, args, env, URL, and headers.
• Trust: servers from shared project files (.mcp.json, .larik/settings.json) don't start until you run /mcp approve <name>. The approval is stored in private project settings and pinned to a hash of the server's config, so editing the command or URL requires re-approval. Servers in personal settings start automatically.
• Permissions: MCP tools ask before running. The exception is tools that declare both readOnlyHint: true and openWorldHint: false.
• Stable tool set: servers start in the background at launch, and their tools are loaded before the first request. The tool set then stays fixed for that context so prompt caches stay valid. Newly approved or restarted servers join after /clear or in a new session.
• Stdio server stderr is written to ~/.local/share/larik/logs/mcp-<name>.log.
• Text results are passed to the model. Images and binary resources are summarized, not sent.
• Resources: when a server offers resources, the model gets list_mcp_resources and read_mcp_resource. You can attach one yourself as @<server>:<uri>; the @ picker lists them under "MCP resources". Text is attached as text and images as images. Images a server's tool returns, such as a screenshot, go to the model too.
• Prompts: a server's prompts are slash commands named /mcp__<server>__<prompt>, listed in the / palette with their arguments. Arguments go in order, split on spaces, and the last one takes the rest of the line. They work with -p too.
• OAuth: an http or sse server that asks for sign-in shows as "needs sign-in" instead of opening a browser at startup. Run /mcp login <name>: Larik opens the server's sign-in page, catches the redirect on 127.0.0.1, and keeps the tokens in ~/.config/larik/mcp-auth/ (owner-only), refreshing them as needed, so -p and larik serve use the sign-in too. /mcp logout <name> forgets it. By default Larik registers itself with the server's authorization server; for a server that needs a pre-registered client, set "oauth": {"client_id": "…", "client_secret": "${SECRET}", "callback_port": 8765}, and "scopes" to choose scopes. For token-based servers, use headers instead.