ContextVM Overview

ContextVM (Context Virtual Machine) is a protocol that bridges the Model Context Protocol (MCP) with the Nostr network, enabling decentralized communication between MCP servers and clients.

Core Concept

ContextVM operates as a transport layer for MCP, using Nostr's relay network as the communication mechanism while preserving MCP's JSON-RPC semantics.

┌─────────────────────────────────────────────────────────────┐
│                    MCP Application Layer                     │
│         (Tools, Resources, Prompts, Sampling)               │
├─────────────────────────────────────────────────────────────┤
│                 ContextVM Transport Layer                    │
│    (Nostr events, Encryption, Public Key Cryptography)      │
├─────────────────────────────────────────────────────────────┤
│                     Nostr Relay Network                      │
│              (wss://relay.contextvm.org, etc.)              │
└─────────────────────────────────────────────────────────────┘

Key Features

• Decentralized Communication: No central servers required; use Nostr's distributed relay network
• Security First: Leverages Nostr's cryptographic primitives for verification and authorization
• Public Key Identity: Servers and clients identified by Nostr public keys
• Optional Encryption: End-to-end encryption via NIP-44 gift wrapping
• Server Discovery: Public server announcements via replaceable events

Protocol Architecture

Three-Layer Design

1. Transport Layer: Nostr events and relays
2. Message Layer: JSON-RPC MCP messages embedded in event content
3. Metadata Layer: Nostr event tags for addressing and correlation

Main Actors

Event Kinds

ContextVM uses these Nostr event kinds:

Message Flow

Connection Process

1. Discovery: Client discovers server via public key or relay queries
2. Initialization: Standard MCP handshake over Nostr
3. Operation: Client calls tools/lists resources via kind 25910 events
4. Termination: Connection closes when either party disconnects

Event Structure

{
  "kind": 25910,
  "pubkey": "<sender-public-key>",
  "content": "{\"jsonrpc\":\"2.0\",...}",
  "tags": [
    ["p", "<recipient-public-key>"],
    ["e", "<correlation-event-id>"]
  ]
}

Security Model

Public Key Cryptography

• All messages cryptographically signed
• Server identity = public key (portable across relays)
• Client authorization via public key whitelisting

Encryption (CEP-4)

• Optional NIP-44 encryption via gift wrap (kind 1059)
• Negotiated during initialization
• Servers advertise support via support_encryption tag

The Nostr Way

ContextVM follows the same core pattern as other Nostr-based RPC systems (like DVMs): publish a signed request event, listen for a correlated response. The difference is in the message structure—CVM uses JSON-RPC via MCP rather than provider-specific payloads.

To understand this foundation:

• Read [references/nostr-way-without-sdks.md](../client-dev/references/nostr-way-without-sdks.md) — The Nostr primitives behind CVM (for non-SDK implementations)

Reference Materials

For detailed specifications, see:

• [references/protocol-spec.md](references/protocol-spec.md) - Full protocol specification
• [references/ceps.md](references/ceps.md) - ContextVM Enhancement Proposals
• [references/mcp-integration.md](references/mcp-integration.md) - MCP protocol integration details

Ecosystem Navigation (what to use when)

Use this decision table to jump to the right component / skill:

Useful public entry points:

• ContextVM docs: https://docs.contextvm.org
• ContextVM org: https://contextvm.org