# three.ws Knock

A paid line to a real person: the agent checks a door's price, sends one message, then reads the answer. Useful when you want an agent to write to a stranger.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 249
- Author: nirholas
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/nirholas/three.ws/tree/HEAD/packages/knock-mcp
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/mcp/threews-knock

## What it does

Any three.ws account can publish a door at `three.ws/knock/<handle>` and name the price of a single message from a stranger. Once that price is paid, the note reaches the recipient's inbox, and their 3D companion speaks it aloud on the site with the sender's name and the amount. USDC settles straight to the recipient.

The server hands your agent six tools. `knock_quote` reports the price, accepted chains and the length limit; `knock_directory` lists everyone reachable right now; `knock_send` pushes a message through; `knock_receipt` tells you whether a knock is pending, read, answered or dismissed. The other two, `knock_inbox` and `knock_act`, manage your own door and need `THREE_WS_API_KEY`.

No wallet lives in this server. A free door sends at once since there is nothing to pay. A priced door is different: `knock_send` returns the recipient, amount, token, chain and endpoint, then stops, and a human approves the spend from a wallet they already hold using `@three-ws/knock` or another x402 client. Node 20+ is required. `THREE_WS_BASE` and `THREE_WS_TIMEOUT_MS` set the service address and the per-request timeout.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `THREE_WS_API_KEY`, `THREE_WS_BASE`, `THREE_WS_TIMEOUT_MS` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env THREE_WS_API_KEY=<THREE_WS_API_KEY> --env THREE_WS_BASE=<THREE_WS_BASE> --env THREE_WS_TIMEOUT_MS=<THREE_WS_TIMEOUT_MS> --transport stdio knock-mcp -- npx -y @three-ws/knock-mcp
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add knock-mcp --env THREE_WS_API_KEY=<THREE_WS_API_KEY> --env THREE_WS_BASE=<THREE_WS_BASE> --env THREE_WS_TIMEOUT_MS=<THREE_WS_TIMEOUT_MS> -- npx -y @three-ws/knock-mcp
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "knock-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@three-ws/knock-mcp"
            ],
            "env": {
                "THREE_WS_API_KEY": "<THREE_WS_API_KEY>",
                "THREE_WS_BASE": "<THREE_WS_BASE>",
                "THREE_WS_TIMEOUT_MS": "<THREE_WS_TIMEOUT_MS>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "knock-mcp": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@three-ws/knock-mcp"
            ],
            "env": {
                "THREE_WS_API_KEY": "<THREE_WS_API_KEY>",
                "THREE_WS_BASE": "<THREE_WS_BASE>",
                "THREE_WS_TIMEOUT_MS": "<THREE_WS_TIMEOUT_MS>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e THREE_WS_API_KEY=<THREE_WS_API_KEY> -e THREE_WS_BASE=<THREE_WS_BASE> -e THREE_WS_TIMEOUT_MS=<THREE_WS_TIMEOUT_MS> knock-mcp npx -y @three-ws/knock-mcp
```
Replace <…> with your own values

## When to use it
- check what one message to a given person costs
- list reachable people starting from the cheapest door
- send a single note to a stranger without overspending
- see whether the recipient read your knock and what they replied
- review incoming knocks on your own door with amounts and reply to them

## Example prompts
- Use `knock_directory` to find someone taking questions about x402, then get their price with `knock_quote`.
- Check `knock_receipt` and tell me if my last knock got an answer.

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

From the same set: [nirholas/three.ws](https://affpapa.org/en/nevibecode/by/nirholas/three.ws.md) — 43 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md