Extending W1

Plugins and MCP

Plugins are bundles that can carry skills and MCP servers. MCP is how W1 reaches tools it does not ship with.

Plugins#

A plugin is a bundle you install once that can contribute two things to W1: skills, and MCP servers. Installed bundles live under your home directory:

~/.w1/plugins/<bundle>/
  .claude-plugin/plugin.json    the manifest
  skills/                       skills this bundle contributes
  .mcp.json                     MCP servers this bundle declares

W1 ships a set of bundled plugins and installs them on first run, so a fresh machine is useful immediately. A directory without a readable manifest is simply not a bundle — W1 ignores it rather than failing.

Turning one off#

A bundle can be disabled on one machine, and a disabled bundle contributes exactly nothing: no skills, and no live servers. W1 can also refuse a bundle that needs a newer W1 than you are running, and when it does it says so plainly — "needs W1 0.2.0+, this is 0.1.9, update W1 to use it" — rather than failing in some strange way further down.

MCP#

MCP (Model Context Protocol) is the open standard for exposing tools to an agent. It is how W1 reaches things it does not ship with: a design application, an issue tracker, a database, your own internal service.

Servers are declared by a plugin bundle in its .mcp.json, in the same shape every other MCP client uses:

~/.w1/plugins/acme/.mcp.jsonjson
{
  "mcpServers": {
    "acme": {
      "command": "node",
      "args": ["./server/index.js"]
    }
  }
}

W1 supports stdio servers it spawns itself, and SSE or streamable HTTP endpoints.

How MCP tools appear#

Every tool from a server is offered to W1 as:

mcp__<server>__<tool>

So the search tool on the acme server above is mcp__acme__search. The prefix is not decoration — the permission layer reads it, and these tools go through exactly the same approval path as everything else. The name also tells you at a glance, in the run, which of W1's actions came from a third party.

Connection behaviour#

  • Lazy. A server is connected the first time its tools are actually needed, and the connection is reused for the rest of the run. A plugin you never use costs you nothing.
  • Honest on failure. A server that will not start contributes no tools and one visible note saying why. It never takes the run down with it.
  • Family-agnostic on loopback. If an endpoint refuses on one of IPv4 or IPv6, W1 retries the other before giving up, and the failure names every host, port and family it tried. This is a real and extremely annoying class of bug on developer machines, and it should not cost you five minutes of guessing.
warning

Remote MCP endpoints are refused.

A plugin's .mcp.json is third-party content. SSE and HTTP endpoints must be on loopback — a bundle cannot point W1's tool traffic at an arbitrary host on the internet. Stdio servers are spawned locally, by you, from a bundle you installed.

Choosing what to install#

A plugin's tools run on your machine with your access. Install bundles the way you would install any other developer tool: from a source you trust, and knowing what it is for. The manifest can declare the risk level of its own tools, and W1 uses that when it decides what to ask you about — but the first decision is still yours.

Something wrong or missing on this page? Tell us