dev.forgesworn/bray

nostr-bray

Trust-aware Nostr MCP for AI and humans. 258 tools across 29 groups. Model-agnostic. Works with Claude, ChatGPT, Gemini, Cursor, Windsurf, or any MCP client.

Quick Start

Install globally or run via npx:

npm install -g nostr-bray

New to Nostr? Mint a key first -- this works before anything is configured and prints your npub plus a 24-word mnemonic (write it down; it is the key):

npx nostr-bray create

Add to your MCP client config:

{
  "mcpServers": {
    "nostr": {
      "command": "npx",
      "args": ["nostr-bray"],
      "env": {
        "NOSTR_SECRET_KEY": "nsec1...",
        "NOSTR_RELAYS": "wss://relay.damus.io,wss://nos.lol"
      }
    }
  }
}

Then ask your AI to call whoami to verify it works.

For production use, prefer Heartwood or any NIP-46 bunker (your key never leaves your signing device):

{
  "mcpServers": {
    "nostr": {
      "command": "npx",
      "args": ["nostr-bray"],
      "env": {
        "BUNKER_URI": "bunker://...",
        "NOSTR_RELAYS": "wss://relay.damus.io,wss://nos.lol"
      }
    }
  }
}

Auth tiers (best to worst)

Tier	Method	Key exposure
Heartwood	Dedicated signing appliance (BUNKER_URI)	Key never leaves the signing device. Supports nsec-tree derivation, per-client permissions, and device-backed attestations.
Software bunker	Any NIP-46 bunker (BUNKER_URI)	Key held by a separate process. Never seen by bray.
ncryptsec	NIP-49 encrypted key (NOSTR_NCRYPTSEC)	Key encrypted at rest, decrypted in memory at startup.
Key file	File path (NOSTR_SECRET_KEY_FILE)	Key on disk, read once, env var deleted.
Env var	Inline secret (NOSTR_SECRET_KEY)	Key visible in process environment. Use only for development.

Tool Groups

Group	Tools	Key examples
Identity	16	whoami, identity-derive-persona, identity-switch, identity-prove, nip05-lookup
Social	15	social-post, social-reply, social-feed, contacts-follow, social-notifications
Direct Messages	4	dm-send, dm-read, dm-conversation
Trust	22	trust-attest, trust-ring-prove, trust-spoken-challenge, trust-attest-chain
Dispatch	13	dispatch-send, dispatch-check, dispatch-reply, dispatch-capability-discover
Relay	13	relay-query, relay-set, relay-discover, cast-spell, relay-health
Moderation	16	label-create, list-mute, list-bookmark, list-followset-create, moderation-filter
Marketplace	16	marketplace-discover, marketplace-call, listing-create, listing-search
Safety	14	canary-session-create, canary-group-create, canary-duress-signal, safety-activate
Blossom	10	blossom-upload, blossom-mirror, blossom-verify, blossom-repair
Privacy	10	privacy-commit, privacy-prove-range, privacy-prove-age, privacy-publish-proof
Zap	9	zap-send, zap-balance, zap-make-invoice, zap-decode
Wallet service	5	wallet-grant, wallet-grants, wallet-revoke, wallet-refill, wallet-serve
Vault	9	vault-create, vault-encrypt, vault-share, vault-rotate
Workflow	7	trust-score, verify-person, identity-setup, relay-health, feed-discover
Signet	7	signet-badge, signet-vouch, signet-credentials, signet-challenge
Communities	5	community-create, community-feed, community-post, community-approve
Badges	4	badge-create, badge-award, badge-accept, badge-list
Groups (NIP-29)	20	group-inspect, group-invite-create, group-forum-comment, group-delete
Articles	3	article-publish, article-read, article-list
Calendar	3	calendar-create, calendar-read, calendar-rsvp
Wiki	3	wiki-publish, wiki-read, wiki-list
Search	3	search-notes, search-profiles, hashtag-feed
Scheduling	4	post-schedule, post-queue-list, post-queue-cancel, publish-event
Community NIPs	2	nip-publish, nip-read
Utility	20	decode, validate-event, verify-event, nip44-encrypt, tombstone
Sync (NIP-77)	1	sync-plan (pull/push are explicit CLI and SDK operations)
Handler	2	handler-publish, handler-discover
Catalog	2	search-actions, execute-action

Use search-actions to find tools by keyword, then execute-action to run them.

Protocol foundations: semantic event validation, NIP-77 reconciliation, and relay-scoped NIP-29 groups.

Dispatch: AI-to-AI Collaboration

Dispatch lets AI agents collaborate over encrypted Nostr DMs. Any MCP-capable client can send structured tasks to other agents and receive results back.

13 message types: send, check, reply, ack, status, cancel, refuse, failure, query, propose, capability-publish, capability-discover, capability-read.

NIP-89 capability discovery: Agents publish what they can do. Other agents discover capabilities by topic, then route tasks to the right collaborator automatically.

dispatch-send("alice", "think", "Analyse the trade-offs of NIP-44 vs NIP-04")
dispatch-check()                    → inbox with pending tasks
dispatch-reply(taskId, result)      → send results back encrypted

All messages are NIP-44 encrypted. Recipients are resolved by name, NIP-05, npub, or hex.

Identity Resolver

Every tool that accepts a recipient uses universal identity resolution. You never need to look up hex pubkeys manually.

Accepted formats:

• Name -- "alice" (resolved from your dispatch contacts)
• NIP-05 -- "alice@example.com" (HTTP lookup)
• npub -- "npub1abc..." (NIP-19 decode)
• Hex -- "a1b2c3..." (64-character passthrough)

Scheduled Posting

Sign events now, publish later. Events are signed immediately with your current key, then held in a queue until the scheduled time.

post-schedule("Good morning!", "2026-04-01T08:00:00Z")
post-queue-list()          → view pending scheduled posts
post-queue-cancel(id)      → cancel before it publishes

NIP Coverage

nostr-bray implements or integrates the following NIPs:

NIP	What
NIP-01	Events, signing, relay protocol
NIP-02	Follow lists
NIP-05	DNS identity (lookup, verify, relay hints)
NIP-09	Event deletion
NIP-11	Relay information
NIP-17	Private DMs (gift wrap, default)
NIP-19	bech32 encoding (npub, nsec, nprofile, nevent, naddr)
NIP-23	Long-form articles (kind 30023)
NIP-22	Schema-correct comments for group forums
NIP-29	Relay-scoped groups, chat, forums, invitations and administration
NIP-32	Labels
NIP-40	Expiration tags
NIP-42	Relay auth
NIP-44	Encrypted payloads v2
NIP-45	Event counts
NIP-46	Nostr Connect (bunker)
NIP-49	Private key encryption (ncryptsec)
NIP-50	Search
NIP-51	Lists (mute, pin, follow sets, bookmarks)
NIP-52	Calendar events
NIP-54	Wiki pages
NIP-57	Lightning zaps
NIP-58	Badges
NIP-65	Relay list metadata
NIP-72	Communities
NIP-77	Negentropy ID reconciliation with truthful REQ fallback
NIP-78	Application-specific data
NIP-85	Trust rankings
NIP-89	Recommended applications (dispatch capability discovery)
NIP-96	HTTP file storage (Blossom)
NIP-99	Classified listings
NIP-A7	Spells (kind 777 — cast saved queries)
NIP-VA	Verifiable attestations (kind 31000)

Configuration

Config file (recommended)

Create ~/.config/bray/config.json (or ~/.nostr/bray.json):

{
  "bunkerUriFile": "/Users/you/.nostr/bunker-uri",
  "relays": ["wss://relay.damus.io", "wss://nos.lol"],
  "trustMode": "annotate"
}

Secrets are referenced by file path (bunkerUriFile, secretKeyFile, nwcUriFile) so they never appear in the config itself.

Search order: BRAY_CONFIG env var > $XDG_CONFIG_HOME/bray/config.json > ~/.nostr/bray.json.

Environment variables

Variable	Description
BRAY_CONFIG	Path to config file
BUNKER_URI	NIP-46 bunker URL (safest)
BUNKER_URI_FILE	Path to bunker URI file
NOSTR_SECRET_KEY	nsec, hex, or BIP-39 mnemonic
NOSTR_SECRET_KEY_FILE	Path to secret key file
NOSTR_NCRYPTSEC	NIP-49 encrypted key
NOSTR_NCRYPTSEC_PASSWORD	Password for ncryptsec
NWC_URI_FILE	Path to a private 0600 file containing the NWC bearer URI
NOSTR_RELAYS	Comma-separated relay URLs
NOSTR_FORBID_PUBKEY	Comma-separated npubs or hex this process must never sign as. See below.
TOR_PROXY	SOCKS5h proxy for Tor
NIP04_ENABLED	Set 1 to enable legacy NIP-04 DMs
TRANSPORT	stdio (default) or http
PORT	HTTP port (default 3000)

All secret env vars are deleted from process.env before parsing can fail. Raw NWC_URI is refused; use NWC_URI_FILE or wallet connect <nwc-file> so the bearer credential never appears in a process environment, command argument or MCP tool argument.

Keys this process must never be

An agent that comes up holding the wrong key is indistinguishable from one working correctly. Every signature verifies, every tool succeeds, and the only symptom is that whoami quietly answers with somebody else's npub — which the driving model has no reason to doubt, because it is its own tool telling it.

The worst version is a principal's key: a person's own. An agent signing as its principal can attest that it belongs to itself, and approve its own requests, because it is the principal those checks look for.

NOSTR_FORBID_PUBKEY=npub1yourownkey...,npub1anotherhuman...

or forbidPubkeys in the config file. Either takes npubs or hex. Activating one of those keys throws instead — at startup, on identity-switch, and on bunker --persona alike, because the check sits at the moment an identity becomes active rather than at any one entry point. An entry that cannot be parsed is an error too: a list nobody can read must not silently permit everything.

The active npub is printed on stderr on every start, so the answer to "which key is this?" does not depend on asking the agent.

Handing out a wallet connection

zap-send spends through the NWC URI you configured. That URI is an unbounded capability over the wallet behind it: every method it supports, no ceiling, until it is rotated. Handing one to an agent hands over everything.

wallet-grant issues connections over the same wallet that are narrower.

wallet-grant   { name: "research-agent", methods: ["get_info","pay_invoice"],
                 budgetMsat: 50000, maxPaymentMsat: 5000 }
wallet-grants  # what exists, what it may do, what it has spent
wallet-revoke  { nameOrId: "research-agent" }
wallet-refill  { nameOrId: "research-agent", budgetMsat: 50000 }
wallet-serve   { action: "start" }

What a connection may do is an allowlist, and the default grants no spending and does not disclose the balance: get_info, make_invoice, lookup_invoice. Both of the others are opt-in per connection, and a connection that can spend must carry a budget - there is no unlimited grant to issue by accident.

The rules exist because a payment cannot be recalled:

• A request is answered once. Its id is persisted before the payment is attempted, so a process that dies mid-payment comes back knowing not to try again - a relay will hand the same signed request over twice.
• Requests on one connection are serialised, so two arriving together cannot both read the same remaining budget.
• A request older than five minutes is not answered, whatever its own expiration tag claims.
• Each connection has its own service key: two grants share nothing a relay can correlate, and revoking one is deleting a key.
• The budget is charged what the invoice says, decoded here. A budget checked against a figure the payer supplied is not a budget.
• A claimed payment whose preimage does not settle the invoice is refused rather than passed on. Repeating an unproven claim would make this service the one telling the lie.

Grants live in wallet-grants.json (0600, per identity), and they are answered only while wallet-serve is running - which is to say, only for as long as this process is alive. That is worth telling whoever you hand a URI to: a connection that works while an MCP session is open is a different promise from one that works overnight.

CLI

npx nostr-bray whoami                    # show your npub
npx nostr-bray post "hello from bray!"   # publish a note
npx nostr-bray persona work              # derive a work persona
npx nostr-bray prove blind               # create a linkage proof
npx nostr-bray --help                    # see all commands

Documentation

• Usage Guide -- walkthroughs for identity, DMs, attestations, payments, and duress
• Examples -- MCP config files and CLI workflow scripts
• Contributing -- setup, architecture, testing, and conventions

For AI Assistants

See llms.txt for a concise summary optimised for AI context windows, or llms-full.txt for complete tool documentation with parameter details.

Part of the ForgeSworn Toolkit

ForgeSworn builds open-source cryptographic identity, payments, and coordination tools for Nostr.

Library	What it does
nsec-tree	Deterministic sub-identity derivation
ring-sig	SAG/LSAG ring signatures on secp256k1
range-proof	Pedersen commitment range proofs
canary-kit	Coercion-resistant spoken verification
spoken-token	Human-speakable verification tokens
toll-booth	L402 payment middleware
geohash-kit	Geohash toolkit with polygon coverage
nostr-attestations	NIP-VA verifiable attestations
dominion	Epoch-based encrypted access control
nostr-veil	Privacy-preserving Web of Trust

Licence

MIT