---
title: Nostr Server Transport
description: A server-side component for exposing MCP servers over Nostr.
---
# Nostr Server Transport
The `NostrServerTransport` is the server-side counterpart to the [`NostrClientTransport`](/transports/nostr-client-transport). It allows an MCP server to expose its capabilities to the Nostr network, making them discoverable and usable by any Nostr-enabled client. Like the client transport, it implements the `Transport` interface from the `@modelcontextprotocol/sdk`.
## Overview
The `NostrServerTransport` is responsible for:
- Listening for incoming MCP requests from Nostr clients.
- Managing individual client sessions and their state (e.g., initialization, encryption).
- Handling request/response correlation to ensure responses are sent to the correct client.
- Sending responses and notifications back to clients over Nostr.
- Optionally announcing the server and its capabilities to the network for public discovery.
## `NostrServerTransportOptions`
The transport is configured via the `NostrServerTransportOptions` interface:
```typescript
export interface NostrServerTransportOptions extends BaseNostrTransportOptions {
serverInfo?: ServerInfo;
profileMetadata?: ProfileMetadata;
/** @deprecated Use isAnnouncedServer instead. */
isPublicServer?: boolean;
isAnnouncedServer?: boolean;
publishRelayList?: boolean;
relayListUrls?: string[];
bootstrapRelayUrls?: string[];
allowedPublicKeys?: string[];
/** Optional callback for dynamic public key authorization. Returns true to allow the pubkey. */
excludedCapabilities?: CapabilityExclusion[];
/** Optional callback for dynamic capability exclusions. Returns true to bypass pubkey authorization. */
isCapabilityExcluded?: (
exclusion: CapabilityExclusion,
logLevel?: LogLevel;
/**
* Whether to inject the client's public key into the _meta field of incoming messages.
* @default false
*/
injectClientPubkey?: boolean;
/**
* Whether to inject the inbound Nostr request event ID into the `_meta` field
* of incoming request messages.
* @default false
*/
injectRequestEventId?: boolean;
}
```
- **`serverInfo`**: (Optional) Information about the server (`name`, `picture`, `website`) to be used in public announcements.
- **`profileMetadata`**: (Optional) NIP-01 `kind:0` metadata for the server profile. When provided, the transport publishes a signed `kind:0` event at startup as defined by CEP-23.
- **`isAnnouncedServer`**: (Optional) If `true`, the transport publishes public announcement events for relay-based discovery. Defaults to `false`.
- **`isPublicServer`**: (Deprecated) Legacy alias for `isAnnouncedServer`.
- **`publishRelayList`**: (Optional) If `true`, the transport publishes a NIP-65 relay list (`kind:10002`) even when `isAnnouncedServer` is `false`. Defaults to `true`.
- **`relayListUrls`**: (Optional) Explicit relay URLs to advertise in the published relay list. If omitted, the SDK derives them from the configured relay handler when possible.
- **`bootstrapRelayUrls`**: (Optional) Extra relays used only as publication targets for discoverability events such as `kind:11316` and `kind:10002`. These are not automatically advertised in the relay list.
- **`allowedPublicKeys`**: (Optional) A list of client public keys that are allowed to connect. If not provided, any client can connect.
- **`isPubkeyAllowed`**: (Optional) A dynamic authorization callback that receives a client public key and returns `true` to allow the connection. Can be async. When used with `allowedPublicKeys`, both checks must pass (AND logic).
- **`excludedCapabilities`**: (Optional) A list of capabilities that are excluded from public key whitelisting requirements. This allows certain operations from disallowed public keys, enhancing security policy flexibility while maintaining backward compatibility.
- **`isCapabilityExcluded`**: (Optional) A dynamic capability exclusion callback that receives a capability exclusion pattern and returns `true` to bypass pubkey authorization for that capability. Can be async. Evaluated after static `excludedCapabilities`.
- **`injectClientPubkey`**: (Optional) If `true`, the transport will inject the client's public key into the `_meta` field of requests passed to the underlying server. Defaults to `false`.
- **`injectRequestEventId`**: (Optional) If `true`, the transport will inject the inbound Nostr request event ID into the `_meta` field of incoming request messages. This enables middleware and tools to access the original Nostr event that triggered the request, including the event's pubkey and full event data through `getNostrRequestEvent()`. Defaults to `false`.
## CEP-23 Server Profile Publication
`serverInfo` and `profileMetadata` serve different purposes:
- **`serverInfo`** powers ContextVM discovery and initialize semantics.
- **`profileMetadata`** powers an optional Nostr social/profile identity via `kind:0`.
This separation matters because some servers want to be discoverable over ContextVM without maintaining a public social profile, while others want both.
### `ProfileMetadata`
The `profileMetadata` object is serialized as JSON and published as a NIP-01 `kind:0` event.
```typescript
export interface ProfileMetadata {
name?: string;
about?: string;
picture?: string;
banner?: string;
website?: string;
nip05?: string;
lud16?: string;
[key: string]: unknown;
}
```
### Publication behavior
- Publication is **opt-in** and only happens when `profileMetadata` is provided.
- `kind:0` publication is independent from `isAnnouncedServer`.
- A server can publish profile metadata even when it does **not** publish public announcement events.
- The profile event is sent through the same discoverability publication path as relay-list and announcement events, so `bootstrapRelayUrls` also help distribute profile metadata in local or non-WebSocket relay environments.
### Example: announced server with a public profile
```typescript
const transport = new NostrServerTransport({
signer,
relayHandler: relayPool,
isAnnouncedServer: true,
publishRelayList: true,
profileMetadata: {
name: 'My Awesome MCP Server',
about: 'Public MCP provider on Nostr',
picture: 'https://example.com/avatar.png',
website: 'https://example.com',
nip05: 'server@example.com',
},
serverInfo: {
name: 'My Awesome MCP Server',
website: 'https://example.com',
},
});
```
### Example: private server with profile publication only
```typescript
const transport = new NostrServerTransport({
signer,
relayHandler: relayPool,
isAnnouncedServer: false,
profileMetadata: {
name: 'Private Profile Server',
about: 'Publishes a CEP-23 profile without public capability announcements',
website: 'https://example.com/private-server',
},
bootstrapRelayUrls: ['wss://relay.damus.io'],
});
```
In this configuration, the server remains outside the public capability-announcement flow but still publishes a canonical Nostr profile that clients and operators can render.
### Capability Exclusion
The `CapabilityExclusion` interface allows you to define specific capabilities that bypass the public key whitelisting requirements:
```typescript
/**
* Represents a capability exclusion pattern that can bypass whitelisting.
* Can be either a method-only pattern (e.g., 'tools/list') or a method + name pattern (e.g., 'tools/call, get_weather').
*/
export interface CapabilityExclusion {
/** The JSON-RPC method to exclude from whitelisting (e.g., 'tools/call', 'tools/list') */
method: string;
/** Optional capability name to specifically exclude (e.g., 'get_weather') */
name?: string;
}
```
#### How Capability Exclusion Works
Capability exclusion provides fine-grained control over access by allowing specific operations to be performed even by clients that are not in the `allowedPublicKeys` list. This is useful for:
- Allowing public access to server discovery endpoints like `tools/list`
- Permitting specific tool calls from untrusted clients
- Maintaining backward compatibility with existing clients
#### Exclusion Patterns
- **Method-only exclusion**: `{ method: 'tools/list' }` - Excludes all calls to the `tools/list` method
- **Method + name exclusion**: `{ method: 'tools/call', name: 'add' }` - Excludes only the `add` tool from the `tools/call` method
## Dynamic Authorization
In addition to static configuration, you can provide dynamic authorization callbacks for more flexible access control policies.
### Dynamic Public Key Authorization
Use `isPubkeyAllowed` to implement runtime authorization logic:
```typescript
const transport = new NostrServerTransport({
signer,
relayHandler: relayPool,
// Static allowlist (optional - can be used alone or with dynamic check)
allowedPublicKeys: ['known-trusted-client'],
// Dynamic authorization callback
isPubkeyAllowed: async (clientPubkey) => {
// Check against a database, external service, or custom logic
const isAllowed = await checkDatabaseForAccess(clientPubkey);
return isAllowed;
},
});
```
When both `allowedPublicKeys` and `isPubkeyAllowed` are configured, a client must pass **both** checks (AND logic) to be authorized.
### Dynamic Capability Exclusions
Use `isCapabilityExcluded` to dynamically determine which capabilities bypass whitelisting:
```typescript
const transport = new NostrServerTransport({
signer,
relayHandler: relayPool,
allowedPublicKeys: ['trusted-client'],
// Static exclusions
excludedCapabilities: [{ method: 'tools/list' }],
// Dynamic exclusion callback - evaluated after static exclusions
isCapabilityExcluded: async (exclusion) => {
// Check if this specific capability should be public
if (exclusion.method === 'tools/call' && exclusion.name === 'get_weather') {
return await isWeatherServicePublic();
}
return false;
},
});
```
The dynamic callback receives the exclusion pattern being checked and returns `true` to allow the capability without pubkey authorization.
### Combining Static and Dynamic Authorization
You can mix static and dynamic approaches for maximum flexibility:
```typescript
const transport = new NostrServerTransport({
signer,
relayHandler: relayPool,
isAnnouncedServer: true,
// Hardcoded trusted clients
allowedPublicKeys: ['admin-pubkey', 'service-account-pubkey'],
// Dynamic check for additional clients
isPubkeyAllowed: async (clientPubkey) => {
// Check subscription status in database
const subscription = await db.subscriptions.findByPubkey(clientPubkey);
return subscription?.isActive ?? false;
},
// Public capabilities anyone can use
excludedCapabilities: [
{ method: 'tools/list' },
{ method: 'tools/call', name: 'get_status' },
],
// Dynamic capability exclusions
isCapabilityExcluded: async (exclusion) => {
// Check feature flags for temporarily public capabilities
if (exclusion.method === 'tools/call') {
return await featureFlags.isToolPublic(exclusion.name);
}
return false;
},
});
```
## Usage Example
Here's how to use the `NostrServerTransport` with an `McpServer` from the `@modelcontextprotocol/sdk`:
```typescript
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { NostrServerTransport } from '@contextvm/sdk';
import { PrivateKeySigner } from '@contextvm/sdk';
import { ApplesauceRelayPool } from '@contextvm/sdk';
// 1. Configure the signer and relay pool
const signer = new PrivateKeySigner('your-server-private-key');
const relayPool = new ApplesauceRelayPool(['wss://relay.damus.io']);
// 2. Create the McpServer instance
const mcpServer = new McpServer({
name: 'demo-server',
version: '1.0.0',
});
// Register your server's tools, resources, etc.
// mcpServer.tool(...);
// 3. Create the NostrServerTransport instance
const serverNostrTransport = new NostrServerTransport({
signer: signer,
relayHandler: relayPool,
isAnnouncedServer: true,
publishRelayList: true,
bootstrapRelayUrls: ['wss://relay.damus.io', 'wss://nos.lol'],
profileMetadata: {
name: 'My Awesome MCP Server',
about: 'Public MCP provider on Nostr',
picture: 'https://example.com/avatar.png',
website: 'https://example.com',
},
serverInfo: {
name: 'My Awesome MCP Server',
website: 'https://example.com',
},
allowedPublicKeys: ['trusted-client-key'], // Only allow specific clients
excludedCapabilities: [
{ method: 'tools/list' }, // Allow any client to list available tools
{ method: 'tools/call', name: 'get_weather' }, // Allow any client to call get_weather tool
],
injectClientPubkey: true, // Enable client public key injection
injectRequestEventId: true, // Enable request event ID injection
});
// 4. Connect the server
await mcpServer.connect(serverNostrTransport);
console.log('MCP server is running and available on Nostr.');
// Keep the process running...
// To shut down: await mcpServer.close();
```
> **Note**: The `relayHandler` option also accepts a `string[]` of relay URLs, in which case an `ApplesauceRelayPool` will be created automatically. See the [Base Nostr Transport](/transports/base-nostr-transport) documentation for details.
## CEP-15 Common Tool Schemas
If your server implements a shared tool contract defined by [CEP-15](/spec/ceps/cep-15), you can opt specific tools into common-schema publication.
Use `withCommonToolSchemas()` to decorate the transport before connecting the server:
```typescript
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import {
ApplesauceRelayPool,
NostrServerTransport,
PrivateKeySigner,
withCommonToolSchemas,
} from '@contextvm/sdk';
const signer = new PrivateKeySigner('your-server-private-key');
const relayPool = new ApplesauceRelayPool(['wss://relay.damus.io']);
const server = new McpServer({
name: 'translation-server',
version: '1.0.0',
});
server.registerTool(
'translate_text',
{
description: 'Translate text between languages.',
inputSchema: {
type: 'object',
properties: {
text: { type: 'string' },
target_language: { type: 'string' },
},
required: ['text', 'target_language'],
},
outputSchema: {
type: 'object',
properties: {
translated_text: { type: 'string' },
},
required: ['translated_text'],
},
},
async ({ text, target_language }) => ({
content: [{ type: 'text', text: `Translated to ${target_language}: ${text}` }],
structuredContent: {
translated_text: `Translated to ${target_language}: ${text}`,
},
}),
);
const transport = withCommonToolSchemas(
new NostrServerTransport({
signer,
relayHandler: relayPool,
isAnnouncedServer: true,
}),
{
tools: [{ name: 'translate_text' }],
},
);
await server.connect(transport);
```
### What the SDK publishes automatically
For each opted-in tool, the SDK:
- computes the CEP-15 schema hash from the tool name plus normalized `inputSchema` and `outputSchema`;
- injects `_meta['io.contextvm/common-schema'].schemaHash` into `tools/list` responses;
- adds matching `i` and `k` tags to tools-list announcement events when the server is announced.
Use this for tools that are intended to match a shared public contract across providers. Bespoke tools should remain outside the common-schema configuration.
### Notes
- Apply `withCommonToolSchemas()` before `server.connect()` so direct responses and announcements stay aligned from the start.
- Tool `name` is part of the schema identity, so renaming a tool changes the resulting hash.
- If you provide an `outputSchema`, it participates in the hash and should remain stable across providers.
- Schemas used for hashing must be self-contained. Remote `$ref` values must be resolved before hashing.
For lower-level hashing and verification utilities, see [Common Tool Schemas](/ts-sdk/core/common-tool-schemas).
## How It Works
1. **`start()`**: When `mcpServer.connect()` is called, the transport connects to the relays and subscribes to events targeting the server's public key. If `isAnnouncedServer` is `true`, it publishes public announcement events. Independently, if `publishRelayList` is enabled, it also publishes relay-list metadata. If `profileMetadata` is configured, it publishes a CEP-23 `kind:0` profile event.
2. **Incoming Events**: The transport listens for events from clients. For each client, it maintains a `ClientSession`.
3. **Request Handling**: When a valid request is received from an authorized client, the transport forwards it to the `McpServer`'s internal logic via the `onmessage` handler. It replaces the request's original ID with the unique Nostr event ID to prevent ID collisions between different clients.
- If `injectClientPubkey` is enabled, the client's public key is injected into the request's `_meta` field before being passed to the server.
- If `injectRequestEventId` is enabled, the inbound Nostr event ID is injected into `_meta.requestEventId`, allowing tools and middleware to retrieve the full event via `getNostrRequestEvent()`.
4. **Response Handling**: When the `McpServer` sends a response, the transport's `send()` method is called. The transport looks up the original request details from the client's session, restores the original request ID, and sends the response back to the correct client, referencing the original event ID.
5. **Discoverability publication**: Public announcement events (kinds 11316-11320) are controlled by `isAnnouncedServer`. Relay-list metadata (`kind:10002`) is controlled independently by `publishRelayList`. Profile metadata (`kind:0`) is controlled independently by `profileMetadata`.
## Relay List Discoverability
Servers can publish a NIP-65 relay list so clients can discover where the server is reachable.
### Default Behavior
- `isAnnouncedServer: true` enables public announcement publication
- `publishRelayList` defaults to `true` for both public and private servers
- if `relayListUrls` is omitted, the SDK derives advertised relays from the configured relay handler when possible
- `bootstrapRelayUrls` can be used to publish discoverability events to extra relays without advertising them as operational relays
### Why bootstrap relays exist
Operational relays and discoverability relays do not always need to be identical:
- **Operational relays** are where the server actually handles requests and responses
- **Bootstrap relays** are additional relays used to make the server easier to discover
This separation helps keep the published relay list focused while still improving network visibility.
## Discoverability event matrix
The transport now exposes three independent publication surfaces:
| ContextVM capability announcements | `11316`-`11320` | `isAnnouncedServer` |
| Relay discoverability | `10002` | `publishRelayList` |
| Nostr profile identity | `0` | `profileMetadata` |
This allows release-time configurations such as:
- fully public servers that publish all three surfaces;
- private servers that only publish relay metadata;
- private or semi-private servers that publish a `kind:0` profile without publishing capability announcements.
## Session Management
The `NostrServerTransport` manages a session for each unique client public key. Each session tracks:
- If the client has completed the MCP initialization handshake.
- Whether the session is encrypted.
- A map of pending requests to correlate responses.
- The timestamp of the last activity, used for cleaning up inactive sessions.
## Security and Policy Flexibility
The capability exclusion feature provides enhanced security policy flexibility by allowing you to create a whitelist-based security model with specific exceptions. This approach is particularly useful for:
### Use Cases
1. **Public Discovery**: Allow any client to discover your server's capabilities via `tools/list` while restricting actual tool usage to authorized clients.
2. **Limited Public Access**: Permit specific, safe operations from untrusted clients while maintaining security for sensitive operations.
3. **Backward Compatibility**: Gradually introduce stricter security policies while maintaining compatibility with existing clients.
4. **Tiered Access**: Create different levels of access where certain capabilities are available to all clients, while others require explicit authorization.
## Client Public Key Injection
When the `injectClientPubkey` option is enabled, the transport injects the client's public key into the `_meta` field of requests passed to the underlying MCP server. This enables servers to access client identification information for authentication, authorization, and enhanced integration purposes.
### How It Works
1. When a request is received from a client, the transport extracts the client's public key from the Nostr event
2. The transport embeds the `clientPubkey` field in the message's `_meta` field
3. The modified request is then passed to the underlying server
The injected metadata follows this structure:
```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "example_tool",
"arguments": {}
},
"_meta": {
"clientPubkey": "<client-public-key-hex>",
"requestEventId": "<nostr-event-id-hex>"
}
}
```
### Use Cases
- **Authentication**: Servers can verify client identity without additional protocol overhead
- **Authorization**: Implement per-client access controls based on public key
- **Logging**: Track client activity and usage patterns
- **Rate Limiting**: Apply rate limits on a per-client basis
- **Personalization**: Provide client-specific responses or data
## Request Event ID Injection
When the `injectRequestEventId` option is enabled, the transport injects the inbound Nostr request event ID into `_meta.requestEventId` on incoming request messages. Tool implementations can then use `getNostrRequestEvent()` to retrieve the full signed Nostr event, including the sender's pubkey and all event metadata.
### Accessing the Full Request Event Inside a Tool
```typescript
import {
NostrServerTransport,
PrivateKeySigner,
ApplesauceRelayPool,
} from '@contextvm/sdk';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
const signer = new PrivateKeySigner('your-server-private-key');
const relayPool = new ApplesauceRelayPool(['wss://relay.damus.io']);
const transport = new NostrServerTransport({
signer,
relayHandler: relayPool,
injectRequestEventId: true,
});
const server = new McpServer({ name: 'demo-server', version: '1.0.0' });
server.registerTool(
'whoami',
{
description: 'Returns the public key of the client that invoked this tool.',
inputSchema: {},
},
async (_args, extra) => {
const requestEventId = extra._meta?.requestEventId;
if (requestEventId) {
const requestEvent = transport.getNostrRequestEvent(requestEventId);
if (requestEvent) {
return {
content: [
{
type: 'text',
text: `Called by ${requestEvent.pubkey} at timestamp ${requestEvent.created_at}`,
},
],
};
}
}
return {
content: [{ type: 'text', text: 'unknown caller' }],
};
},
);
await server.connect(transport);
```
## Structured Tool Outputs
`NostrServerTransport` does not change the MCP tool result model, so structured outputs work the same way they do on any other MCP transport. This is especially useful when your server is meant for programmatic usage and clients should be able to depend on a stable result shape.
Define an `outputSchema` on the tool and return `structuredContent` from the handler:
```typescript
server.registerTool(
'get_weather',
{
description: 'Get weather information for a city',
inputSchema: z.object({
city: z.string(),
country: z.string(),
}),
outputSchema: z.object({
temperature: z.object({
celsius: z.number(),
fahrenheit: z.number(),
}),
conditions: z.enum(['sunny', 'cloudy', 'rainy', 'stormy', 'snowy']),
humidity: z.number().min(0).max(100),
}),
},
async ({ city, country }) => {
const structuredContent = {
temperature: {
celsius: 22,
fahrenheit: 71.6,
},
conditions: 'sunny' as const,
humidity: 45,
};
return {
content: [
{
type: 'text',
text: `Weather for ${city}, ${country}: ${structuredContent.temperature.celsius}°C and ${structuredContent.conditions}.`,
},
],
structuredContent,
};
},
);
```
Guidance:
- Use `structuredContent` for machine-readable output.
- Use `content` for human-readable output only.
- `content` does not need to duplicate `structuredContent`.
- If no human-readable output is needed, `content` can be `[]`.
## Next Steps
Now that you understand how the transports work, let's dive into the **[Signer](/signer/nostr-signer-interface)**, the component responsible for cryptographic signatures.