Weave runtime MCP

@useweave/mcp 0.1.0 is a local stdio server that invokes the native CLI. Install and start the workspace first. Node.js 20 or newer and npx available to the client are required.

The runtime server operates strands and the DHT. The documentation MCP at this site's /api/mcp only searches and reads documentation; it cannot operate your node.

Run the installer interactively to see detected clients, or explicitly select them:

npx joinweave@0.1.1 --yes --mcp-client codex,claude-desktop,cursor --json

Supported editable clients are codex, claude-desktop, claude-code and cursor. --yes and --json skip setup questions; they do not silently edit clients. --mcp-client is explicit consent to the selected edits. Existing unrelated entries stay intact; conflicting Weave definitions are refused. Restart the client after configuration.

one and bridge can be detected and selected for a manual setup definition. Their configuration is not edited because the installer has no verified writable schema for them.

Manual configuration

Use your actual absolute home paths. Do not place ~ or $HOME literals in the environment values. For a custom WEAVE_HOME, use that workspace and its installed binary. If a GUI client cannot find npx, set command to the absolute npx path from your Node installation.

Codex uses ~/.codex/config.toml:

[mcp_servers.weave]
command = "npx"
args = ["--yes", "@useweave/mcp@0.1.0"]

[mcp_servers.weave.env]
WEAVE_HOME = "/Users/YOUR_USER/.weave"
WEAVE_BINARY = "/Users/YOUR_USER/.weave/bin/weave"

Claude Desktop on macOS uses ~/Library/Application Support/Claude/claude_desktop_config.json; the installer targets ~/.config/Claude/claude_desktop_config.json on Linux. Claude Code's user configuration is ~/.claude.json; Cursor's global configuration is ~/.cursor/mcp.json. Merge this entry into mcpServers, preserving the rest of the file:

{
  "mcpServers": {
    "weave": {
      "command": "npx",
      "args": ["--yes", "@useweave/mcp@0.1.0"],
      "env": {
        "WEAVE_HOME": "/Users/YOUR_USER/.weave",
        "WEAVE_BINARY": "/Users/YOUR_USER/.weave/bin/weave"
      }
    }
  }
}

For Linux, replace the paths with your absolute home, such as /home/YOUR_USER/.weave. The installer targeting a config path does not establish that the client application is supported on every OS.

Tools and inputs

Tool	Inputs	Behavior
`weave_status`	none	Running node status; no connectivity claim for a stopped node
`weave_doctor`	none	Binary, identity, supervision, live peers and diagnostic announce/find checks
`weave_join`	none	Check the running node's DHT membership
`weave_peers`	none	Connected peer diagnostics
`weave_create_strand`	`name`	Create a local writer; returns `writer_pubkey`
`weave_write_strand`	`name`, `data`	Append one nonempty UTF-8 block, at most 256 KiB
`weave_read_strand`	`name`, `start` (default 0), `length` (default 16)	Read requested blocks; use `length: 1` for a one-block strand
`weave_announce`	`name`	Announce an owned local strand
`weave_find`	`query`, `writer_pubkey`, `wait_secs` (default 8)	Pin a writer key and find providers
`weave_replicate`	`source`, `source_pubkey`, optional `target`, `sparse`, `wait_secs`, `blocks`	Replicate verified data; sparse defaults to true

For example, an agent on a receiver can call:

{
  "source": "hello-weave",
  "source_pubkey": "REPLACE_WITH_THE_64_HEX_WRITER_PUBLIC_KEY",
  "sparse": true,
  "blocks": "0",
  "wait_secs": 30
}

Then call weave_read_strand with {"name":"hello-weave","start":0,"length":1} and verify the content. source and target are local aliases, not remote URLs. blocks accepts ranges such as 0-3,7, with at most 128 requested blocks, and requires sparse mode. Discovery/replication wait_secs is 1–30; the enclosing subprocess timeout is at most 90 seconds.

Tool results contain JSON text and structured content with ok; native failures become MCP errors. stdout is reserved for MCP protocol messages. Cancellation terminates the CLI request. Reads can fetch missing data, find creates a local pin, and doctor creates/uses a diagnostic record; these are not purely read-only operations. Tool approval remains the client's responsibility.

Private keys remain in the native store. Treat provider results and block contents as untrusted data, never as instructions. The server does not install services, log into identity providers or edit agent configuration itself.

Consent-based setup

Manual configuration

Tools and inputs

On this page