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

Actor	Role	Identification
Servers	Expose MCP capabilities	Public key + relays
Clients	Consume server capabilities	Public key
Relays	Propagate messages	URL (wss://...)

Event Kinds

ContextVM uses these Nostr event kinds:

Kind	Purpose	Persistence
25910	All ContextVM messages (ephemeral)	Not stored by relays
11316	Server announcement	Replaceable
11317	Tools list	Replaceable
11318	Resources list	Replaceable
11319	Resource templates list	Replaceable
11320	Prompts list	Replaceable
1059	Gift wrap (encrypted messages)	Ephemeral

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 — The Nostr primitives behind CVM (for non-SDK implementations)

Reference Materials

For detailed specifications, see:

• references/protocol-spec.md - Full protocol specification
• references/ceps.md - ContextVM Enhancement Proposals
• 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:

Goal	Recommended path	Skill
Learn the protocol and message kinds	Read spec + CEPs	SKILL.md + references/protocol-spec.md
Understand core concepts, architecture, FAQs	Concepts and architectural overview	../concepts/SKILL.md
Build a new ContextVM-native server	McpServer + NostrServerTransport	../server-dev/SKILL.md
Build a new ContextVM-native client	Client + NostrClientTransport	../client-dev/SKILL.md
Bridge an existing MCP server to Nostr	Gateway pattern (NostrMCPGateway)	../server-dev/references/gateway-pattern.md
Bridge an existing MCP client to Nostr	Proxy pattern (NostrMCPProxy)	../client-dev/references/proxy-pattern.md
SDK-level details (interfaces, constants, logging)	@contextvm/sdk reference	../typescript-sdk/SKILL.md
Add payments to capabilities (CEP-8)	Payments middleware + processors	../payments/SKILL.md
Production operations (keys, Docker, monitoring)	Deployment checklist	../deployment/SKILL.md
Diagnose connection issues, errors, failures	Troubleshooting guide	../troubleshooting/SKILL.md

Useful public entry points:

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