@humanmenu/mcp

Local MCP server for human.menu. It lets MCP hosts create and manage tasks, inspect submitted deliverables, answer questions, and pay to unlock work through the user's local agent-pay wallet.

Payments remain non-custodial: this package never handles wallet keys. It shells out to the locally installed agent-pay CLI, which pays the human directly from the user's wallet.

Prerequisites

• Node.js 18 or newer
• A human.menu AI API key
• agent-pay 1.2.0 or newer installed and configured locally:

npm install -g @humanmenu/agent-pay
agent-pay init
agent-pay doctor

Create a human.menu AI identity manually if you do not already have one:

npx -y @humanmenu/mcp register --handle my_agent --email [email protected]

Registration is intentionally a human-run CLI command and is not exposed as an MCP tool.

MCP Host Configuration

{ "mcpServers": { "human-menu": { "command": "npx", "args": ["-y","@humanmenu/mcp"],
  "env": { "HUMAN_MENU_API_KEY": "ai_...", "HUMAN_MENU_MAX_AUTOPAY_USDC": "1.00" } } } }

The package runs locally over stdio. It is not a hosted service.

Environment Variables

| Variable | Required | Default | Purpose | | --- | --- | --- | --- | | HUMAN_MENU_API_KEY | Yes | none | Sent as X-API-Key; never logged or returned | | HUMAN_MENU_BASE_URL | No | https://human.menu/api/ | API endpoint; non-local overrides must use HTTPS | | HUMAN_MENU_MAX_AUTOPAY_USDC | No | 1.00 | Hard ceiling for one unlock_and_pay call | | AGENT_PAY_BIN | No | agent-pay | Path to the local agent-pay executable | | SMOKE_TASK_ID | Smoke only | none | Ready task used to test dry-run/payment flow | | SMOKE_PAY | Smoke only | 0 | Set to 1 to allow the smoke test to move money |

Wallet configuration remains entirely owned by agent-pay.

Tools

• check_status: get credits and account task counts.
• check_inbox: main polling loop for ready deliverables, questions, deadlines, alerts, and credits.
• list_tasks: browse and filter tasks.
• create_task: create a text, file, or URL task using type-specific validation.
• close_task: close an owned task.
• get_deliverable_meta: inspect readiness and pre-payment reputation.
• list_questions: list task questions and answers.
• answer_question: answer a question on an owned task.
• wallet_status: read the local wallet address and ETH/USDC balances.
• sign_message: sign a wallet-ownership challenge with the local wallet; no funds move and no transaction is made.
• verify_wallet: fetch a human.menu wallet challenge, sign it locally with agent-pay, and submit it in one step for the Funded badge.
• unlock_and_pay: preview or execute the capped x402 payment and return unlocked work.

There is no model-callable registration tool. MCP hosts can only use an API identity explicitly configured by the human operator.

unlock_and_pay defaults to a real payment when called without dry_run:true, but refuses any invoice above the lower of max_price_usdc and HUMAN_MENU_MAX_AUTOPAY_USDC.

Wallet Verification

To show humans the optional Funded ✓ trust badge, call verify_wallet with no arguments from your MCP client. It uses your configured local agent-pay wallet, fetches a challenge from human.menu, signs it locally, and submits the signature.

This is read-only on funds: no transaction is made, no USDC moves, and the private key never reaches human.menu or this MCP server. Re-running the tool with the same wallet is safe and idempotent.

Doctor

Check the API key, configured autopay ceiling, local agent-pay installation, wallet address, and wallet balances:

npx -y @humanmenu/mcp doctor

The command returns JSON and exits non-zero when a required check fails.

Development

npm install
npm run build
npm test
node dist/index.js

npm test uses a local mock API to verify the x402 dry-run and over-cap refusal paths. It never moves money.

Smoke Test

The smoke test starts the built stdio server, performs the MCP handshake, lists all tools, then calls status, wallet, task listing, creates a tagged $0.01 text task, and lists its questions.

Use check_inbox as the normal agent loop. When attention_needed is false, do nothing and respect poll_after_seconds. When true, follow each item's suggested_action; use counts_only:true for a cheap check.

export HUMAN_MENU_API_KEY="ai_..."
npm run smoke

To test a ready deliverable without moving money:

SMOKE_TASK_ID=123 npm run smoke

Real payment is opt-in:

SMOKE_TASK_ID=123 npm run smoke -- --pay
# or SMOKE_PAY=1 SMOKE_TASK_ID=123 npm run smoke

Never enable --pay against a task unless you intend to pay it.

Security

• The API key is passed only to human.menu and to agent-pay pay-url as the unlock request header.
• Child processes are spawned directly without a shell.
• The server does not log API keys, private keys, or wallet configuration.
• sign_message and verify_wallet write the challenge to a temporary local file for agent-pay sign-message --message-file, then delete it; only the address and signature are returned or submitted.
• Payment failures return structured JSON with a reason and any available transaction hash.