Plugins

A plugin gives bots tools for a service or an app. Under the hood a plugin is one or more MCP servers.

The marketplace

Click the marketplace icon (four circles) at the bottom right of the sidebar, or choose File › Marketplace… (⇧⌘M, or Ctrl+Shift+M on Windows and Linux). It lists Featured Plugins and Featured Bots first, then everything by category. View all under a featured section lists every plugin or every bot. Search finds plugins and bots together. The marketplace comes from lorca.app, so new plugins and bots show up without updating Beans.

The marketplace has these plugins:

Browser, Context7, DeepWiki, Exa, and Hugging Face work without an account. Zapier reaches the apps that have no plugin here, such as Gmail, Google Calendar, and Slack. The bots in the marketplace are ready-made teammates; see Bots.

Plugins are installed per Runner. Every bot on that computer can use every plugin installed there. Secrets and sign-ins stay on that Runner; your other devices only see the plugin's name and state.

On-demand tools

A bot starts a turn with only a small catalog of the plugins installed on its Runner. Beans connects an MCP server and gives the model matching tool schemas only when the task needs that capability. The selected tools remain available for the rest of that turn, while unrelated plugin catalogs stay out of the model's context.

Install a plugin

• From a chat: ask the bot. "Install the GitHub plugin." It finds the plugin and posts a card asking your permission before it installs anything.
• From the app: open the marketplace and click Add beside a plugin. It installs on the Runner shown at the top of the marketplace; pick another one there if you have more. Add from Plugins… in a bot's inspector opens the marketplace on that bot's Runner, and Settings › Plugins on the Runner picked in the toolbar.

You can install a plugin on any Runner from your phone. The request travels to that computer encrypted.

Sign in

A plugin that needs an account posts a sign-in card in the chat: Sign in or Not now.

• GitHub shows a short code and a link (on the plugin's sheet too, when you sign in there). Enter the code on github.com from any device.
• Other services open a sign-in page in the browser on the Runner. If you are on another device, the card tells you to finish there.

Some plugins take a pasted token instead, which also suits a Runner with no browser: a GitHub personal access token, or an API key or token for Airtable, Cloudflare, Fireflies, Neon, PostHog, Resend, Stripe, Supabase, or Zapier. Context7 and Exa take an optional API key that raises their free limits, and Hugging Face a token that brings your own account. Fill it in on the plugin's sheet. Secret fields are write-only: once saved they are never shown again.

What a plugin may do

Reading runs right away. Anything that changes something, such as creating an issue, posting a comment, or deleting a page, goes through Auto-review, and asks you first when it should.

Manage a plugin

A plugin's sheet shows its state, its sign-in, its settings, the actions you have always allowed (with Reset), and Remove. Marketplace plugins update themselves and keep your settings and sign-ins.

Your own MCP servers

Any MCP server can be a plugin: a command the Runner starts, such as npx -y @modelcontextprotocol/server-filesystem ~/Notes, uvx mcp-server-fetch, or a docker run, or the URL of a remote server that speaks streamable HTTP.

Settings › Plugins lists them under MCP Servers for the Runner picked in the toolbar. Add Server… takes a name and either the command (with its environment variables) or the URL (with its headers). Paste the JSON a server's README gives, or a whole mcpServers block from Claude Desktop or Cursor, into any field, and the sheet reads it; several servers are added at once. Once saved, the sheet shows whether the server started and the tools it offered, with Reconnect, a switch that turns it off, and Remove. A server you turn off keeps its settings and sign-in, and no bot sees it.

A remote server that needs an account asks for it when Beans first connects: the server reads Needs a sign-in, and Sign in, on its sheet or on a card a bot posts, signs in with OAuth as for a marketplace plugin, and Sign Out on its sheet forgets the sign-in. A server that takes a token instead gets it in a header, such as Authorization: Bearer ….

The servers live in mcp.json in Beans's folder (~/.lorca/mcp.json), in the format Claude Desktop, Cursor, and Claude Code use, so you can copy one from their configs or edit the file by hand. After editing it, click Reload on its row in Settings › Plugins, or run lorca mcp reload:

{
  "mcpServers": {
    "notes": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/Notes"],
      "description": "My notes folder"
    },
    "linear": {
      "type": "http",
      "url": "https://mcp.linear.app/mcp"
    },
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp",
      "headers": { "CONTEXT7_API_KEY": "${CONTEXT7_API_KEY}" },
      "disabled": true
    }
  }
}

${VAR} reads a variable from your shell's environment, and ${VAR:-default} falls back to the default; a header or variable whose value is not set is left out. description tells bots what the server is for, cwd is the folder a command starts in, timeout is how many seconds a call may go without an answer (ten minutes when unset), and "oauth": false stops a remote server from signing in. Beans keeps the fields it does not know, and the order you wrote.

To keep some of a server's tools from bots, turn off their switches on the server's sheet, or write them in toolExposure, as pi does: { "delete_*": "hidden", "delete_draft": "codemode" } hides every tool whose name starts with delete_ except delete_draft, since a name wins over a pattern. "exposure": "hidden" hides every tool the server's toolExposure doesn't name.

A server that doesn't register apps on the fly takes the one you registered with it in oauth: clientId, clientSecret (which can be ${SECRET}), and the callbackPort or callbackUrl you registered, whose sign-in opens in the Runner's own browser. clientName registers Beans under another name, for a server that only takes names it knows; scope asks for more access; and authServerMetadataUrl points at the right authorization server when the server names the wrong one. When a server answers that a call needs more access than the sign-in has, it asks you to sign in again, for that access too.

Bots call a server's tools by its name, notes__read_file, and reading tools run at once while the rest go through Auto-review, as for any plugin. A server that offers resources, such as files or records, also gets tools to list and read them, notes__list_mcp_resources and notes__read_mcp_resource; binary resources are saved to a file the bot can open. The command line manages the same file: lorca mcp add, list, get, remove, reload, sign-out, and import from another app.