Willow STDIO Library

@mcp-s/mcp is the Willow STDIO library: a local MCP server that speaks stdio to your AI client and connects it to your Willow basecamp.

What is Willow?

Willow is the identity and access layer for AI agents at work. Instead of every employee wiring their own MCP servers with personal API keys, Willow gives an organization one control plane: admins connect tools once (1000+ connectors, plus API-to-MCP conversion for internal endpoints), scope them by identity with least-privilege permissions, and get a full audit trail of every action an agent takes — with approvals, guardrails, and a kill switch when something goes wrong.

What this library does

This package is the client-side half of that: the piece that runs on your machine so your AI client can reach the tools your admin approved.

• Runs as a stdio MCP server. Any MCP client that can spawn a process (Cursor, Claude Desktop, Claude Code, VS Code, and others) can use it.
• Serves your whole Willow basecamp. Tools, resources and prompts from every integration connected in Willow show up in your client, scoped to what your identity is allowed to use.
• Handles authentication for you. No API keys to copy around. The first run opens a browser sign-in through your organization's identity provider; the session is cached in ~/.willow and refreshed when it expires.
• Proxies local MCP servers. Servers your organization configured to run locally are spawned and bridged through the same connection, so a single entry in your client config covers everything.
• Logs and audits. Every tool call is reported back to Willow's audit trail, and everything the server does is written to a local log file for debugging.

Installation

Add Willow to your client's MCP configuration:

{
  "mcpServers": {
    "Willow": {
      "command": "npx",
      "args": ["-y", "@mcp-s/mcp"],
      "env": {
        "ORG": "<YOUR_ORG>"
      }
    }
  }
}

Replace <YOUR_ORG> with your organization identifier, save the file, and restart the client. Per-client setup instructions live in the Willow docs.

Signing in

On first start the server has no session yet, so it exposes a single authenticate tool. Ask your assistant to authenticate (or call the tool directly) and a browser window opens for sign-in. Once you finish, the session is saved to ~/.willow and the full tool list is pushed to your client immediately — no restart needed.

Environment variables

| Variable | Description | | --- | --- | | ORG | Your organization identifier. Required unless BASE_URL is set. | | BASE_URL | Custom base URL for the Willow service. Defaults to https://${ORG}.mcp-s.com/mcp. | | TOOLKIT | Comma-separated toolkit slugs to scope the connection to. | | MCP | Comma-separated MCP server slugs to scope the connection to. | | MESH | Set to true to serve five discovery meta-tools instead of the full catalog. Off by default. | | AUTH_MESSAGE | Custom description for the authenticate tool. Defaults to This returns a url that authenticates the user. | | LIST_TOOLS_TIMEOUT_MS | Timeout for tools/list before falling back to just the authenticate tool. Defaults to 2 minutes. | | MAX_TOOLS | Opt-in cap on how many tools are returned in one tools/list response. Above it, a single explanatory tool is returned asking you to scope with TOOLKIT or MCP. Off by default. |

If your basecamp exposes a large catalog, scope the connection with TOOLKIT or MCP so your client only loads the tools it actually needs.

Mesh mode

A large basecamp can put hundreds of tool schemas into the model's context before it has read a single message. MESH=true swaps that for five meta-tools, mirroring the hosted /mcp-mesh endpoint, and lets the model pull in only what a task needs:

| Tool | What it does | | --- | --- | | search_tools | Ranked search across every server, by keyword or phrase. | | get_mcp_servers | Lists the servers you have access to, with tool counts. | | get_mcp_tools | Lists the tools on one server. | | get_tool_details | Returns descriptions and input schemas for chosen tools. | | execute_tool | Runs a tool by server and tool slug. |

{
  "mcpServers": {
    "Willow": {
      "command": "npx",
      "args": ["-y", "@mcp-s/mcp"],
      "env": {
        "ORG": "<YOUR_ORG>",
        "MESH": "true"
      }
    }
  }
}

Search runs locally against your catalog, so it costs no round trip and no model call. It is ranked rather than filtered: a query matches on the tool's slug, display name, description and the server it belongs to, weighted in that order, and tools matching every term always come before tools matching only some. Along the way it handles the things a model actually types — "send a message in slack" finds slack__send_message past the stop words, issues finds create_issue, repo finds list_repositories, and chanel finds list_channels. When nothing matches, the response carries the closest tools as did_you_mean instead of an empty list, so the model can recover without another guess.

The catalog is fetched on the first discovery call rather than at startup, so tools/list returns immediately, and calls go through the same permission checks, guardrails and audit trail as the regular tools. Mesh mode composes with TOOLKIT and MCP: discovery only ever sees the scoped catalog. Prompts and resources are unaffected — they are listed as usual.

Logs

Everything the server writes to console — plus uncaught exceptions, unhandled promise rejections and shutdown signals — is appended to a log file in the same install directory as the saved session:

~/.willow/logs/mcp-s.log

Each spawned local MCP server also gets its own ~/.willow/logs/server-<id>.log containing that server's stderr. The main log rotates at 5 MB, keeping the three previous generations (mcp-s.log.1 … mcp-s.log.3). Access keys and tokens are replaced with [redacted] before anything is written.

Logging is controlled by these optional environment variables:

• WILLOW_LOG_LEVEL: debug, info (default), warn, error or silent. Use debug when troubleshooting — it adds every upstream HTTP call, its status and timing, plus the arguments of each tool call.
• WILLOW_LOG_DIR: write logs somewhere other than ~/.willow/logs.
• WILLOW_LOG_MAX_SIZE_MB: rotation threshold in MB (default 5).
• WILLOW_HOME: relocate the whole install directory (session and logs).

Learn more

• docs.withwillow.ai — admin and user guides, connector setup, and the API reference.
• withwillow.ai — the platform, the connector marketplace, and everything else Willow does.