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

Transport Layer: Nostr events and relays
Message Layer: JSON-RPC MCP messages embedded in event content
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

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

Event Structure

json

{
  "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`
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

overview

NPX Install

Tags

SKILL.md Content