Use this path when you are building a native ContextVM server in Rust.
The recommended architecture is:
- define an
rmcpserver handler - create a
NostrServerTransport - attach the transport to the handler with
rmcp'sServiceExt
This is the same model used by the standard rmcp server examples, except the transport is Nostr instead of stdio.
In rmcp, a native server is normally started with YourHandler.serve(transport).
For ContextVM, the transport becomes NostrServerTransport. In the current SDK API, you pass that transport directly to ServiceExt; there is no extra adapter step in the public workflow.
If the server should run under a stable Nostr identity, load the signer from an existing private key with from_sk():
use contextvm_sdk::signer;
let signer = signer::from_sk("<hex-or-nsec-private-key>")?;
println!("server pubkey: {}", signer.public_key().to_hex());This is the right choice for long-lived servers, announced servers, and deployments where clients must recognize the same public key across restarts.
use contextvm_sdk::transport::server::{
NostrServerTransport, NostrServerTransportConfig,
};
use contextvm_sdk::{signer, EncryptionMode, GiftWrapMode, ServerInfo};
use rmcp::{
ServerHandler, ServiceExt,
handler::server::wrapper::Parameters,
model::*,
schemars, tool, tool_handler, tool_router,
};
const RELAY_URL: &str = "wss://relay.contextvm.org";
#[derive(Clone)]
struct DemoServer {}
impl DemoServer {
fn new() -> Self {
Self {}
}
}
#[derive(Debug, serde::Deserialize, schemars::JsonSchema)]
struct EchoParams {
message: String,
}
#[tool_router]
impl DemoServer {
#[tool(description = "Echo a message back unchanged")]
async fn echo(
&self,
Parameters(EchoParams { message }): Parameters<EchoParams>,
) -> Result<CallToolResult, ErrorData> {
Ok(CallToolResult::success(vec![Content::text(format!(
"Echo: {message}"
))]))
}
}
#[tool_handler]
impl ServerHandler for DemoServer {
fn get_info(&self) -> rmcp::model::ServerInfo {
rmcp::model::ServerInfo::new(ServerCapabilities::builder().enable_tools().build())
.with_server_info(
Implementation::new("contextvm-native-echo", "0.1.0")
.with_title("ContextVM Native Echo Server")
.with_description("Native rmcp echo server over ContextVM/Nostr"),
)
.with_instructions("Call the echo tool with a message string")
}
}
#[tokio::main]
async fn main() -> anyhow::Result<()> {
tracing_subscriber::fmt()
.with_env_filter(
tracing_subscriber::EnvFilter::from_default_env()
.add_directive("contextvm_sdk=info".parse()?)
.add_directive("rmcp=warn".parse()?),
)
.init();
let signer = signer::generate();
let pubkey = signer.public_key().to_hex();
println!("Native ContextVM echo server starting");
println!("Relay: {RELAY_URL}");
println!("Server pubkey: {pubkey}");
let transport = NostrServerTransport::new(
signer,
NostrServerTransportConfig::default()
.with_relay_urls(vec![RELAY_URL.to_string()])
.with_encryption_mode(EncryptionMode::Optional)
.with_gift_wrap_mode(GiftWrapMode::Optional)
.with_announced_server(false)
.with_server_info(
ServerInfo::default()
.with_name("contextvm-native-echo".to_string())
.with_about("Native rmcp echo server example".to_string()),
),
)
.await?;
let service = DemoServer::new().serve(transport).await?;
println!("Server ready. Press Ctrl+C to stop.");
service.waiting().await?;
Ok(())
}This follows the same flow as the repository's native echo server example.
NostrServerTransport is not just a byte stream adapter. It adds ContextVM-specific behavior on top of rmcp server semantics:
- Nostr relay connectivity via
NostrServerTransport::new() - public announcements via
announce() - publication of tools, resources, prompts, and resource templates
- client authorization via
allowed_public_keysinNostrServerTransportConfig - capability exclusions via
CapabilityExclusion - encryption negotiation and response mirroring via
send_response() - session management and request routing inside the server event loop
Start with these fields in NostrServerTransportConfig:
relay_urls: relays the server will publish to and listen onis_announced_server: whether the server should participate in public discoveryencryption_mode: plaintext vs encrypted policygift_wrap_mode: persistent vs ephemeral wrapping policyopen_stream: CEP-41 open-stream settings; disabled by default, opt in withwith_open_stream(OpenStreamConfig::enabled())allowed_public_keys: allowlist for private or restricted serversexcluded_capabilities: allow specific methods without fully opening the serverrelay_list_urls: relay URLs advertised in kind 10002 (CEP-17); defaults torelay_urlsbootstrap_relay_urls: additional relays for publishing announcements (CEP-6/17); merged withrelay_list_urlspublish_relay_list: whether to publish kind 10002 relay list metadata; defaulttrueprofile_metadata: optional profile metadata for kind 0 publication (CEP-23)
When open-stream is enabled and a tools/call request carries a progressToken,
the transport injects an OpenStreamWriter into the request extensions before
dispatch. Tool handlers retrieve it with
ctx.extensions.get::<OpenStreamWriter>() (imported from
contextvm_sdk::transport::open_stream), write chunks with writer.write(..),
and finish with writer.close(). The final CallToolResult is returned normally
after the stream closes. Open-stream is disabled by default; enable it with
with_open_stream(OpenStreamConfig::enabled()). See
open-stream.md for a full example.
Every inbound request carries its caller's Nostr public key. The rmcp worker
injects it into the request extensions, so a tool, resource, or prompt handler
reads it from ctx.extensions:
use contextvm_sdk::transport::server::ClientPubkey;
use rmcp::handler::server::wrapper::Parameters;
use rmcp::model::{CallToolResult, Content, ErrorData};
use rmcp::service::RequestContext;
use rmcp::{tool, RoleServer};
#[tool(description = "Echo the caller's pubkey")]
async fn whoami(
&self,
ctx: RequestContext<RoleServer>,
) -> Result<CallToolResult, ErrorData> {
let pk = ctx.extensions.get::<ClientPubkey>().map(|c| c.0.clone());
Ok(CallToolResult::success(vec![Content::text(pk.unwrap_or_default())]))
}ClientPubkey lives in contextvm_sdk::transport::server (also re-exported at
the crate root). It is present on every real inbound request, so retrieving it
never returns None for a genuine client call. This mirrors the TS adapter's
extra._meta.clientPubkey, but via rmcp's typed extensions instead of the
on-wire _meta field. The inbound Nostr event id is available separately as
ctx.id (the worker rewrites the request id to the event id).
When a handler needs the full client-signed request event — not just the
pubkey — the worker also injects an InboundEvent into extensions. This
exposes the event's id, pubkey, sig, tags, …, which matters when a
handler must bind a tool call to the publishing event, store it for later
return, or audit it. sig in particular is the client's Schnorr signature and
cannot be reconstructed by the server (it does not hold the client's private
key), so it has to be threaded through from ingest.
use contextvm_sdk::transport::server::InboundEvent;
use rmcp::handler::server::wrapper::Parameters;
use rmcp::model::{CallToolResult, Content, ErrorData};
use rmcp::service::RequestContext;
use rmcp::{tool, RoleServer};
#[tool(description = "Return the inbound event's id + sig")]
async fn audit(
&self,
ctx: RequestContext<RoleServer>,
) -> Result<CallToolResult, ErrorData> {
match ctx.extensions.get::<InboundEvent>() {
Some(ev) => Ok(CallToolResult::success(vec![Content::text(format!(
"id={} sig={}",
ev.0.id.to_hex(),
ev.0.sig // Display renders hex
))])),
None => Err(ErrorData::invalid_params("no inbound event", None)),
}
}For gift-wrapped requests this is the inner, signature-verified event (the
same one whose pubkey is surfaced as ClientPubkey, so ev.0.pubkey and
ClientPubkey agree by construction); for plaintext requests it is the outer
request event. It is injected only for real client requests — synthetic
transport-internal requests (announcement / initialization drives, CEP-22
oversized reassembly) carry no event, so get::<InboundEvent>() returns None
for them. Like ClientPubkey, this is local-only and never touches the wire.
Use this page's approach when you are writing a new Rust MCP server.
Use the gateway guide when you already have a request loop or existing local MCP service abstraction and want a thinner bridge.
- The
rmcpserver handshake followsServiceExt::serve()on the server handler. rmcpaccepts pre-init ping and enters the main loop immediately after initialization completes.- ContextVM response routing depends on request event ids.
- Encryption mirroring and announcement behavior are covered by the integration tests.
- Announcement publishing is started by the rmcp worker just after
start()(not bytransport.start()itself, because it injects synthetic MCP requests that need an rmcp handler to answer). Whenis_announced_serveristrue, the transport publishes the gated announcement events via those synthetic requests: kind 11316 (server announcement) and kinds 11317-11320 (tools, resources, templates, prompts). - Independently of
is_announced_server, it also publishes kind 10002 (relay list, whenpublish_relay_listis true (the default) and the advertised relay URLs are non-empty) and kind 0 (profile metadata, whenprofile_metadatais configured).