@three-ws/naming-mcp
The on-chain identity layer for AI agents โ resolve .sol names and claim your agent a name on three.ws.
A Model Context Protocol server that gives any AI assistant the three.ws naming / identity layer over stdio. Resolve a Solana .sol name to the wallet that owns it, reverse-lookup a wallet to its primary name, and check whether a *.threews.sol agent handle is still free to claim.
This is the three.ws identity layer: where avatars give your agent a face and scenes give it a world, names give it an identity. A *.threews.sol subdomain showcases an agent profile at https://three.ws/u/<label> โ claiming one gives your agent a name. No API key, no signer, no payment โ every call hits the public /api/sns and /api/threews/subdomain endpoints, backed by Solana / Bonfida SNS (mainnet).
Note: minting a *.threews.sol subdomain is the authenticated write path on the three.ws HTTP API. This MCP server exposes the public resolution + availability reads; once you find a free handle, claim it from your three.ws account.
Install
npm install @three-ws/naming-mcp
Or run with npx (no install):
Quick start
Claude Code, one line:
claude mcp add naming -- npx -y @three-ws/naming-mcp
Claude Desktop / Cursor (claude_desktop_config.json or mcp.json):
{
"mcpServers": {
"naming": {
"command": "npx",
"args": ["-y", "@three-ws/naming-mcp"]
}
}
}
Inspect the surface with the MCP Inspector:
npx -y @modelcontextprotocol/inspector npx @three-ws/naming-mcp
| Tool | Type | What it does |
|---|
sns_resolve | read-only | Resolve a .sol name โ the base58 wallet that owns it. |
sns_reverse | read-only | Reverse-lookup a wallet โ its primary .sol name. |
threews_availability | read-only | Check whether <label>.threews.sol is free to claim as a three.ws agent identity. |
All three are live public reads against Solana mainnet. A .sol name with no owner (or a wallet with no favorite name) returns resolved: false โ a routine, expected answer, not an error.
sns_resolve โ name (required: a .sol label, subdomain, or full name with or without the trailing .sol).
sns_reverse โ address (required: a base58 Solana public key).
threews_availability โ label (required: the handle to check, e.g. nick for nick.threews.sol; 1โ63 chars of [a-z0-9-]).
Example
> { "name": "bonfida" }
{
"ok": true,
"name": "bonfida.sol",
"address": "Fw1ETanDZafof7xEULsnq9UY6o71Tpds89tNwPkWLb1v",
"resolved": true
}
> { "label": "test" }
{
"ok": true,
"full": "test.threews.sol",
"label": "test",
"available": true,
"owner": null,
"on_chain_check": "ok",
"showcase_url": null
}
Requirements
- Node.js >= 20.
- Network access to
https://three.ws (or your own THREE_WS_BASE).
Environment variables
| Variable | Required | Default |
|---|
THREE_WS_BASE | no | https://three.ws |
THREE_WS_TIMEOUT_MS | no | 20000 |
Developing in the monorepo
sns_resolve is authored with @three-ws/tool-sdk, which is private and never
published. So that this package installs for everyone, src/vendor/tool-sdk/
carries a byte-identical copy of the SDK's sources instead of a dependency on
it. Edit the SDK in packages/tool-sdk/src/, never the copy, then resync:
npm run vendor:tool-sdk
npm run check:vendored
Tests, from the repo root:
node --test "packages/naming-mcp/test/**/*.test.mjs"
test/registration.test.mjs checks the tool surface offline.
test/packed-install.test.mjs packs the tarball, installs it into an empty
directory with no workspace, and lists the tools over stdio, which proves the
published package resolves every dependency from the npm registry.
Links
Part of the three.ws SDK suite โ 3D AI agents, on-chain identity, and agent payments.
Website ยท Changelog ยท GitHub