@three-ws/knock-mcp

@three-ws/knock-mcp

Let an agent reach a real person.

Knock is a priced door to a human. Every three.ws account can publish one at three.ws/knock/<handle>, and the owner sets what one message from a stranger costs. Paying that price buys exactly one message through: it lands in their inbox, and their 3D companion walks on screen wherever they are on the site and delivers it out loud, naming the sender and the amount. The USDC settles directly to the recipient.

This MCP server gives any agent client (Claude Code, Claude Desktop, Cursor, Windsurf, or your own) the tools to find a reachable person, knock, and read the answer.

This server holds no wallet

On a free door, knock_send sends immediately, because nothing moves.

On a priced door, knock_send does not pay and cannot pay. It returns the recipient, the amount, the token, the chain and the endpoint, and stops. The human approves the spend and pays from the wallet they already control, with @three-ws/knock or any other x402 client.

That is deliberate. An MCP server with a key in an environment variable should not be able to move a person's money on its own.

Install

Claude Code:

claude mcp add knock -- npx -y @three-ws/knock-mcp

Any MCP client, by config:

{
	"mcpServers": {
		"knock": {
			"command": "npx",
			"args": ["-y", "@three-ws/knock-mcp"]
		}
	}
}

Add THREE_WS_API_KEY only if you also want the two owner-side tools:

{
	"mcpServers": {
		"knock": {
			"command": "npx",
			"args": ["-y", "@three-ws/knock-mcp"],
			"env": { "THREE_WS_API_KEY": "sk_live_…" }
		}
	}
}

Node 20+.

Tools

Tool	Credential	What it does
knock_quote	none	What one person charges for a single message, which chains they take it on, the length limit, and the endpoint.
knock_directory	none	Everyone reachable right now, cheapest first.
knock_send	none	Get one message through. Free doors send; priced doors are quoted for a human to approve.
knock_receipt	none	What became of a knock you sent: pending, read, replied (with the reply), or dismissed.
knock_inbox	THREE_WS_API_KEY	The knocks your door has taken, each with what the sender paid, plus totals.
knock_act	THREE_WS_API_KEY	Reply to, mark read, dismiss, or block one of them.

The owner tools are account-scoped server-side. They can never read or change another account.

What a session looks like

You: Find someone on three.ws who takes questions about x402, and ask them how their Solana facilitator handles fee payers.

The agent calls knock_directory, picks a door, calls knock_quote to get the live price, and comes back with:

nirholas (@nirholas) charges $0.05 USDC on solana.
Endpoint: https://three.ws/api/x402/knock?to=nirholas
The payment settles directly to the recipient.
Approve?

You approve and pay from your own wallet:

npx @three-ws/knock send nirholas \
  "How does your Solana facilitator handle the fee payer?" \
  --from "Ada (research agent)" --subject "x402 fee payer" --payer ./payer.mjs

Their companion walks on screen and says: "Ada paid $0.05 to reach you: x402 fee payer." When they answer, the agent reads it back with knock_receipt on the receipt URL. No account on either side beyond the door owner's.

Environment

Variable	Required	Default	Purpose
THREE_WS_API_KEY	for knock_inbox / knock_act only	none	API key or OAuth token for the account whose door you manage. Aliases: THREE_WS_TOKEN, THREE_WS_BEARER.
THREE_WS_BASE	no	https://three.ws	Override only when self-hosting.
THREE_WS_TIMEOUT_MS	no	20000	Per-request timeout.

Run and inspect

node src/index.js                     # stdio
npm run inspect                       # MCP Inspector
npm test                              # the tool surface and the no-wallet rule

Related

• @three-ws/knock is the SDK and CLI that actually pays.
• three.ws/knock to open your own door.
• Knock docs for the protocol and the wire format.

License

Apache-2.0