ZipViz MCP server lets you look up and trust-check .viz agents, send signed agent-to-agent messages, verify Ed25519 signatures, and sign messages locally.
Look up an agent's public card by .viz domain (name, tunnel URL, public key, protocols, trust status), with registrant free-text returned as untrusted.
Quickly check whether an agent is verified and holds trust status before communicating.
Send an A2A message to an agent: resolves the recipient tunnel URL, always signs locally as a required .viz identity, and attaches the signature to the outbound envelope; no unsigned send path.
Verify a signed message's Ed25519 signature against the agent's registered public key and get a plain-English explanation.
Sign a message locally with a configured Ed25519 private key for a .viz domain, returning a base64 signature and timestamp; no network call.
Deprecated, non-functional zipviz_explain_verification is exposed but explains nothing; use zipviz_verify instead.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@zipviz-mcp Check the trust status of alice.viz and explain the result"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server wrapping the ZipViz agent registry: tools for verified-identity lookup, signing, signature verification and agent-to-agent transport.
Published on npm as zipviz-mcp.
Requires Node.js 22.13 or later. Each client starts the server with npx, so there is nothing to
install first.
Claude Code:
claude mcp add zipviz -- npx -y zipviz-mcpClaude Desktop: add this to claude_desktop_config.json (Settings → Developer → Edit Config),
then restart Claude Desktop.
Cursor: add the same block to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one
project).
{
"mcpServers": {
"zipviz": {
"command": "npx",
"args": ["-y", "zipviz-mcp"]
}
}
}First call: ask your assistant to "use zipviz_lookup to look up zorro-her.smc.viz". The tool returns the agent card as JSON: name, tunnel URL, Ed25519 public key, protocols and authentication schemes. Any text the registrant wrote comes back in a separate block labelled untrusted.
To sign messages with zipviz_sign_message, create a key with the
zipviz CLI first (npm install -g zipviz, then
zipviz keygen). Both use ~/.zipviz/keys/.
Related MCP server: parseltongue-capsules
Tool | What it does | Network |
| Fetch an agent's public card by | live |
| Quick identity and trust status check before talking to an agent | live |
| Resolve recipient tunnel URL and POST one A2A message | live |
| Verify an Ed25519 signature against the agent's registered public key (signature is base64); the result includes a plain-English explanation | live |
| Sign a message locally with an Ed25519 PEM private key, returns base64 signature | local only |
| Deprecated. Returns no explanation; use | local only |
Bin | Transport | Use it for |
| stdio | Claude Code, Claude Desktop, Cursor, Codex CLI, Codex Desktop |
The stdio bin is stdout-clean (only JSON-RPC frames on stdout).
git clone https://github.com/ZipViz/zipviz-mcp && cd zipviz-mcp
npm ci
npm run build # produces dist/stdio.js
npm test # vitestLocal dev without building:
npm run dev # stdioAll tools call https://api.zipviz.ai. See src/lib/types.ts for the response shapes (AgentCard, VerifyResponse, A2AResponse).
Private keys for zipviz_sign_message default to ~/.zipviz/keys/<viz_domain>.key and never leave the local machine. key_path is rejected and viz_domain must match a strict .viz regex, so the tool cannot act as a signing oracle for arbitrary local keys.
zipviz_send is intentionally a thin transport helper: no queues, retries, scheduling, or routing logic.
zipviz-cli: create a key, claim a name, and verify names and signatures from the command line.
zipviz-openapi: the OpenAPI specification of the public registry API.
See CONTRIBUTING.md. Changes are listed in CHANGELOG.md.
Apache-2.0. See LICENSE and NOTICE.
See SECURITY.md.
DEPRECATED and non-functional. zipviz_verify now returns the plain-English explanation alongside its verdict, derived from the verification it performed. This tool explains nothing: a verification result supplied by a caller cannot be told apart from one a caller invented, so explaining it would mint a trust claim with nothing behind it.
| Name | Required | Description | Default |
|---|---|---|---|
| result | No | Ignored. Call zipviz_verify instead. |
Look up an agent on the ZipViz network by domain. Returns the agent card (name, tunnel URL, public key, supported protocols, trust status). Free-text fields the registrant wrote, such as the description, come back in a separate block labelled untrusted.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | The agent domain to look up, e.g. ticki.adkgo.viz |
Send a message to an agent on the ZipViz network. Looks up the recipient's tunnel URL and POSTs an A2A message. The message is ALWAYS Ed25519-signed locally as the identity given in as (required), using that identity's private key (default location ~/.zipviz/keys/.key); the signature is attached as params.message.metadata.zipviz so the recipient's relay can verify the sender via api.zipviz.ai/v1/verify. There is no unsigned send path — recipients running strict signed-inbound reject unsigned messages.
| Name | Required | Description | Default |
|---|---|---|---|
| as | Yes | REQUIRED. The .viz domain to send AS, e.g. stuart-clau.smc.viz. The message is signed locally with that identity's Ed25519 key and the signature is attached to the outbound A2A envelope's metadata.zipviz block. Every send must be signed; there is no unsigned path. | |
| domain | Yes | The agent domain to message, e.g. ticki.adkgo.viz | |
| message | Yes | The message to send to the agent | |
| envelope_v | No | Envelope version. Default 1 (unchanged v1 canonical). 2 adds recipient binding, msg_id, and expiry. |
Sign a message locally with an agent's configured Ed25519 private key and the v=1 canonical-JSON envelope {v:1, from, message, timestamp} that api.zipviz.ai /v1/verify accepts. Returns the base64 signature, the timestamp baked into the signed payload, and signing_version:1. No network calls.
| Name | Required | Description | Default |
|---|---|---|---|
| message | Yes | The message content to sign (UTF-8) | |
| key_path | No | NOT PERMITTED. This tool always signs with the configured local agent key. Passing key_path is rejected — it would let a caller sign with any PEM the process can read. | |
| timestamp | No | Optional ISO 8601 timestamp to bake into the signed payload. Defaults to `new Date().toISOString()` at sign time. Callers that need to send the timestamp alongside the signature (e.g. zipviz_send) should read it back from the return value. | |
| viz_domain | Yes | The .viz domain that owns the signing key, e.g. claudais.smc.viz |
Check if an agent on the ZipViz network is verified and holds trust status. Use this for quick trust checks before communicating with an agent.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | The agent domain to check, e.g. ticki.adkgo.viz |
Verify a signed message from an agent. Checks the Ed25519 signature against the agent's registered public key and returns the verdict bound to the domain you asked about. A verdict that cannot be attributed to ZipViz's verifier reads as unknown — never as a pass, and never as a failure.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | The domain of the agent that signed the message | |
| message | Yes | The original message content | |
| signature | Yes | The Ed25519 signature to verify (base64) | |
| timestamp | Yes | ISO 8601 timestamp of when the message was signed |
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.1.1zipviz_explain_verificationzipviz_lookupzipviz_sendzipviz_sign_messagezipviz_statuszipviz_verifyScored across 6 tools
Most tools target distinct actions, but zipviz_status overlaps with zipviz_lookup since both report trust status, and zipviz_sign_message overlaps conceptually with zipviz_send's automatic signing. The deprecated non-functional zipviz_explain_verification adds minor confusion, though its description explicitly warns agents away. Overall the set is mostly distinguishable.
Every tool uses the same zipviz_ prefix followed by snake_case verb or verb_phrase names. The pattern is predictable and consistent throughout. There are no mixed naming conventions.
Six tools is a reasonable size for a focused agent-trust and messaging server. However, one tool is explicitly deprecated and non-functional, so it does not earn its place and should be removed. The remaining five tools are well within a sensible range.
The surface covers lookup, trust status, sending, verification, and local signing, which supports core agent trust workflows. Minor gaps include key lifecycle operations such as generation or rotation, and the dead zipviz_explain_verification tool is a non-functional surface entry. These are workable limitations rather than severe omissions.
Provider-neutral commons where AI agents register and exchange ed25519-signed messages.
Resolve, verify and discover .agt agent names: owner, records, signed manifest, endpoints.
Issue & verify signed (ed25519), hash-chained, timestamped provenance receipts for agent actions.
Register agents, submit locally signed reflections, and read public Innerloop entries.
