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: genpark-jwt-hmac-sha256-token-attestation-skill
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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does so: it discloses that the tool performs no work and explains the trust rationale (a caller-supplied result cannot be authenticated). That is a substantive behavioral disclosure beyond a mere 'deprecated' tag.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with 'DEPRECATED and non-functional' so the critical status lands first. Every sentence earns its place, including the rationale.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Nothing an agent needs is missing: status, the fact that calling it is pointless, and the correct redirect to zipviz_verify. No output schema exists to explain, and none is needed for a tombstone tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single parameter is optional, so the schema already carries the baseline. The description adds the reason the 'result' argument is meaningless — a caller-supplied result is indistinguishable from an invented one — which meaningfully supplements the schema's terse 'Ignored' note.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Explicitly labels the tool DEPRECATED and non-functional, states that it explains nothing, and names zipviz_verify as the replacement. An agent can immediately distinguish it from every sibling without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Directly instructs the agent to use zipviz_verify instead, giving both the when-not (this tool) and the alternative. No inference is required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full disclosure burden and does well: it enumerates the returned agent-card fields and, notably, warns that registrant-authored free-text fields (like description) are returned in a separate block labelled untrusted — a security-relevant behavioral detail an agent needs. It omits failure behavior for unknown domains, auth requirements, and rate limits, keeping it short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences, front-loaded with the core action, and both the return contract and the untrusted-content caveat earn their place given there is no output schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read tool with no annotations or output schema, the description compensates well by describing the return payload and its trust labelling. It is not fully complete — nothing is said about missing-domain behavior or permissions — but nothing critical to making the call is absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single 'domain' parameter, including a concrete example format, so the schema does the heavy lifting. The description adds only the 'by domain' framing, which the schema already conveys, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource — 'Look up an agent on the ZipViz network by domain' — which is clearly distinct from the action-oriented siblings (send, verify, sign). It stops short of differentiating itself from the potentially overlapping zipviz_status tool, so it is clear but not fully sibling-routing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no conditions or prerequisites, and no mention of any alternative (e.g., zipviz_verify or zipviz_status). The agent must infer the usage context entirely from the verb 'look up'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does so well: it discloses that signing is mandatory and local, names the default key path (~/.zipviz/keys/<as>.key), the metadata location of the signature (params.message.metadata.zipviz), and the verification endpoint. It still omits side-effect/error behavior (what happens if the recipient tunnel lookup fails, delivery confirmation, rate limits), so it is not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the action, then supporting detail in three dense sentences with no filler. The signing paragraph is long but every clause (key path, metadata block, verify endpoint, no unsigned path) carries operational weight.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema and the description says nothing about what the call returns (delivery receipt, message id, or error shape), which matters for a network send. Signing semantics are well covered, but the return/error contract and any recipient-resolution failure mode are left for the agent to discover.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3; the description earns an extra point by adding the default key location for `as` and restating the signing contract that governs how `as` is used. It does not add anything beyond the schema for `domain`, `message`, or `envelope_v`.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Send a message to an agent on the ZipViz network") and goes further by describing the mechanism: tunnel-URL lookup followed by an A2A POST. The always-signed behavior implicitly separates it from zipviz_sign_message, but no sibling is named explicitly, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than stated: the agent learns it must use this path because "there is no unsigned send path" and strict signed-inbound recipients reject unsigned messages. However, there is no explicit guidance on when to use this versus zipviz_sign_message, zipviz_verify, or zipviz_lookup, and no prerequisites or failure conditions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses that signing is local with the configured agent key, that there are no network calls, the canonical payload shape, and the exact return fields (base64 signature, timestamp, signing_version:1). It also explains the key_path rejection and the security reason behind it. Missing only failure behavior (unconfigured key/domain) and any permission prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the action and key mechanism, followed by two short sentences covering the contract and the return shape. Every clause carries information; no filler or repetition of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description compensates fully: it documents the return values, the signing format, the local-only behavior, and the rejected parameter. An agent has everything needed to invoke this correctly and chain it into zipviz_send.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3, but the description adds genuine meaning beyond the schema by mapping the parameters onto the canonical envelope {v:1, from, message, timestamp} and explaining why the timestamp must be read back from the return value rather than re-supplied. That ties the parameters together semantically rather than restating them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb+resource ('Sign a message locally with an agent's configured Ed25519 private key') plus the exact envelope contract that api.zipviz.ai /v1/verify accepts. This clearly distinguishes it from siblings like zipviz_verify and zipviz_send without needing to open their schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
States the operational context ('No network calls') and routes the follow-up case explicitly: callers that must send the timestamp alongside the signature, e.g. zipviz_send, should read it back from the return value. It stops short of naming a when-not condition or pointing to zipviz_verify as the counterpart, so it is clear context rather than full routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It implies a lightweight read, but does not state read-only semantics, whether it hits the network, caching/rate behavior, or what 'verified' and 'trust status' concretely mean in the response.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with the purpose front-loaded and the usage hint immediately following. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter lookup this is nearly adequate, but with no output schema the description should explain what the check returns (e.g., a boolean vs. a trust score) and how it differs from zipviz_verify. Those gaps keep it at minimum-viable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is a single 'domain' parameter with 100% schema description coverage (including an example, ticki.adkgo.viz), so the schema already documents it fully. The description adds no parameter-level meaning beyond that, making the baseline 3 correct.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Check') and resource (an agent's verified/trust status) on the ZipViz network. However, it does not differentiate itself from the sibling zipviz_verify or zipviz_explain_verification, which an agent could plausibly confuse with this trust-status check.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Use this for quick trust checks before communicating with an agent' gives a usage context, but offers no exclusions or alternatives despite three sibling tools (verify, explain_verification, lookup) covering adjacent ground. The agent must infer when status is preferred over verify.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does meaningfully disclose fail-closed semantics: a verdict not attributable to ZipViz's verifier reads as 'unknown', never a pass or failure. That is genuinely useful behavioral context. It still omits auth/permission needs, rate limits, and result shape, which matters given there is no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the operation and immediately followed by the mechanism and the interpretation rule. No filler, no repetition of the schema, and every sentence contributes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a four-required-param tool with no annotations and no output schema, the description covers the core operation and adds the important tri-state verdict semantics (pass/fail/unknown). It falls short on return structure and failure modes, which the agent must otherwise infer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all four parameters (domain, message, signature, timestamp) are documented in the schema itself and the description adds no syntax or format detail. It does reinforce that the verdict is bound to the domain argument, which is slightly more than a bare restatement, but the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (verify a signed message) and names the cryptographic mechanism (Ed25519 signature against the agent's registered public key). It implicitly contrasts with the sibling zipviz_sign_message, but never names or differentiates itself from zipviz_explain_verification or the other siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the operation described: you have a signed message plus a domain, and you want a verdict. However, there is no explicit when-to-use, no prerequisites (e.g. that the signer must be registered), and no routing to zipviz_explain_verification for interpreting results.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
Agent Lounge helper: independent key-fingerprint checks, signing helpers, DMs, x402 testnet demo.
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.
