MCP Server Library

A minimal, general-purpose implementation of the Model Context Protocol (MCP).

Works on Node.js and Bare runtime (Pear/Holepunch).

Features

• Tools — Register functions that AI clients can call
• Resources — Expose data that clients can read (static or dynamic)
• Resource Templates — URI patterns with parameters (user://{id})
• Annotations — Metadata hints for tools and content (MCP 2025-11-25)
• Notifications — Push updates to connected clients
• Subscriptions — Clients can subscribe to resource changes
• Multiple Transports — HTTP, WebSocket, SSE, stdio

Quick Start

import { createMCPServer } from 'bare-mcp'
import { createHttpTransport } from 'bare-mcp/http'

// Create server
const mcp = createMCPServer({
  name: 'my-server',
  version: '1.0.0'
})

// Register a tool
mcp.addTool({
  name: 'greet',
  description: 'Say hello to someone',
  inputSchema: {
    type: 'object',
    properties: {
      name: { type: 'string', description: 'Name to greet' }
    },
    required: ['name']
  },
  execute: async ({ name }) => `Hello, ${name}!`
})

// Start HTTP server (works on both Node.js and Bare)
await createHttpTransport(mcp, { port: 3000 })

Tools

Tools are functions that AI clients can invoke.

mcp.addTool({
  name: 'calculate',
  description: 'Perform arithmetic',
  inputSchema: {
    type: 'object',
    properties: {
      a: { type: 'number' },
      b: { type: 'number' },
      op: { type: 'string', enum: ['add', 'subtract', 'multiply', 'divide'] }
    },
    required: ['a', 'b', 'op']
  },
  execute: async ({ a, b, op }) => {
    const ops = { add: a + b, subtract: a - b, multiply: a * b, divide: a / b }
    return JSON.stringify({ result: ops[op] })
  }
})

// Register multiple tools
mcp.addTools([tool1, tool2, tool3])

Tool Annotations

Tools can include annotations that describe their behavior:

mcp.addTool({
  name: 'search',
  description: 'Search the web',
  inputSchema: {
    type: 'object',
    properties: { query: { type: 'string' } },
    required: ['query']
  },
  execute: async ({ query }) => `Results for: ${query}`,
  annotations: {
    title: 'Web Search',        // Human-readable title
    readOnlyHint: true,         // Doesn't modify environment (default: false)
    openWorldHint: true         // Interacts with external systems (default: true)
  }
})

// Destructive tool example
mcp.addTool({
  name: 'delete_file',
  description: 'Delete a file',
  inputSchema: {
    type: 'object',
    properties: { path: { type: 'string' } },
    required: ['path']
  },
  execute: async ({ path }) => { /* ... */ },
  annotations: {
    title: 'Delete File',
    readOnlyHint: false,        // Modifies environment
    destructiveHint: true,      // May destroy data (default: true)
    idempotentHint: true,       // Repeated calls have same effect (default: false)
    openWorldHint: false        // Only affects local system
  }
})

Annotation	Default	Description
title	—	Human-readable display name
readOnlyHint	false	If true, tool doesn't modify its environment
destructiveHint	true	If true, tool may destroy data (only when readOnlyHint=false)
idempotentHint	false	If true, repeated calls have no extra effect (only when readOnlyHint=false)
openWorldHint	true	If true, interacts with external systems

Tool Results with Annotations

Tools can return rich content with annotations:

mcp.addTool({
  name: 'analyze',
  execute: async () => [{
    type: 'text',
    text: 'Analysis results...',
    annotations: {
      audience: ['user'],           // Who content is for: 'user', 'assistant', or both
      priority: 0.9                  // Importance: 0.0 (optional) to 1.0 (required)
    }
  }]
})

// Return error with content
mcp.addTool({
  name: 'fetch',
  execute: async () => ({
    content: [{ type: 'text', text: 'Connection timeout' }],
    isError: true
  })
})

Error Handling

Tools can throw MCPError with specific error codes:

import { MCPError, ErrorCode } from 'bare-mcp'

mcp.addTool({
  name: 'get_user',
  inputSchema: {
    type: 'object',
    properties: { id: { type: 'string' } },
    required: ['id']
  },
  execute: async ({ id }) => {
    const user = await db.findUser(id)
    if (!user) {
      throw new MCPError(
        ErrorCode.INVALID_PARAMS,
        `User not found: ${id}`,
        { userId: id }  // Optional data field
      )
    }
    return JSON.stringify(user)
  }
})

// Custom error codes (use values > -32000)
mcp.addTool({
  name: 'rate_limited_api',
  execute: async () => {
    throw new MCPError(-32001, 'Rate limit exceeded', { retryAfter: 60 })
  }
})

Standard Error Codes:

Code	Name	Description
-32700	PARSE_ERROR	Invalid JSON
-32600	INVALID_REQUEST	Not a valid JSON-RPC request
-32601	METHOD_NOT_FOUND	Method does not exist
-32602	INVALID_PARAMS	Invalid parameters (validation, missing args)
-32603	INTERNAL_ERROR	Internal server error
-32002	RESOURCE_NOT_FOUND	Resource not found

Error responses follow the JSON-RPC 2.0 spec:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "User not found: abc123",
    "data": { "userId": "abc123" }
  }
}

Resources

Resources expose data that clients can read.

Static Resource

mcp.addResource({
  uri: 'config://app',
  name: 'App Configuration',
  description: 'Application settings',
  mimeType: 'application/json',
  text: JSON.stringify({ theme: 'dark', version: '1.0' })
})

Dynamic Resource

mcp.addResource({
  uri: 'stats://live',
  name: 'Live Statistics',
  mimeType: 'application/json',
  read: async () => JSON.stringify({
    uptime: process.uptime(),
    memory: process.memoryUsage()
  })
})

Resource Annotations

Resources support annotations for display hints and content metadata:

mcp.addResource({
  uri: 'doc://readme',
  name: 'README',
  title: 'Project Documentation',     // Human-readable title
  mimeType: 'text/markdown',
  text: '# My Project',
  annotations: {
    audience: ['user'],               // Who content is for
    priority: 0.9,                    // Importance (0.0 to 1.0)
    lastModified: '2025-01-15T10:00:00Z'
  }
})

Dynamic resources can return annotations per-read:

mcp.addResource({
  uri: 'cache://data',
  name: 'Cached Data',
  read: async () => ({
    text: JSON.stringify(getCachedData()),
    annotations: {
      lastModified: new Date().toISOString(),
      audience: ['assistant']
    }
  })
})

Annotation	Type	Description
audience	string[]	Who content is for: ["user"], ["assistant"], or ["user", "assistant"]
priority	number	Importance: 0.0 (optional) to 1.0 (required)
lastModified	string	ISO 8601 timestamp of last modification

Resource Templates

URI patterns that extract parameters:

mcp.addResourceTemplate({
  uriTemplate: 'user://{id}',
  name: 'User by ID',
  description: 'Fetch user details',
  mimeType: 'application/json',
  read: async ({ id }) => {
    const user = await db.getUser(id)
    return JSON.stringify(user)
  }
})

// Client can read: user://alice, user://bob, etc.

Notifications

Push updates to connected clients.

// Resource was modified
mcp.notifyResourceUpdated('stats://live')

// Resource list changed (added/removed)
mcp.notifyResourceListChanged()

// Tool list changed
mcp.notifyToolListChanged()

// Progress update for long operations
mcp.notifyProgress('upload-token', 50, 100)

// Custom notification
mcp.notify('notifications/custom', { data: 'anything' })

Transports

Runtime detection is automatic — bare-mcp/http and bare-mcp/stdio use which-runtime to pick the correct implementation (Node.js or Bare) at import time. Downstream packages never need to worry about it.

HTTP Transport

The HTTP transport supports three connection modes, all served from the same server:

Mode	Endpoint	Protocol	Direction
Streamable HTTP	POST /mcp	JSON-RPC over HTTP	Request → Response
SSE	GET /sse + POST /message	JSON-RPC over SSE	Bidirectional
WebSocket	ws://host:port	JSON-RPC over WS	Bidirectional

Starting the Server

import { createMCPServer } from 'bare-mcp'
import { createHttpTransport } from 'bare-mcp/http'

const mcp = createMCPServer({ name: 'my-server', version: '1.0.0' })

mcp.addTool({
  name: 'greet',
  description: 'Say hello',
  inputSchema: {
    type: 'object',
    properties: { name: { type: 'string' } },
    required: ['name']
  },
  execute: async ({ name }) => `Hello, ${name}!`
})

const transport = await createHttpTransport(mcp, {
  port: 3000,
  host: '0.0.0.0',
  websocket: true,   // Enable WebSocket (default: true, Node.js only)
  verbose: false,     // Log requests/notifications to stderr (default: false)
  onActivity: (entry) => console.log('Tool called:', entry.tool)
})

HTTP Endpoints

Method	Path	Description
POST	/mcp or /	JSON-RPC endpoint (Streamable HTTP)
GET	/sse	SSE stream (bidirectional MCP transport)
POST	/message?sessionId=...	SSE message endpoint (paired with /sse)
GET	/health	Health check ({ status, server, version, requestCount })
GET	/activity	Recent tool call activity log
POST	/activity/clear	Clear activity log
WS	ws://host:port	WebSocket (Node.js only)

Streamable HTTP (Recommended)

The simplest mode. Clients send a JSON-RPC request via POST and receive the response in the HTTP body. This is the transport that Cursor, Claude Code, and most modern MCP clients use.

// Client sends a request
const res = await fetch('http://localhost:3000/mcp', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'initialize',
    params: {
      protocolVersion: '2025-03-26',
      capabilities: {},
      clientInfo: { name: 'my-client', version: '1.0.0' }
    },
    id: 1
  })
})
const { result } = await res.json()
// result.serverInfo, result.capabilities, etc.

// Call a tool
const toolRes = await fetch('http://localhost:3000/mcp', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'tools/call',
    params: { name: 'greet', arguments: { name: 'World' } },
    id: 2
  })
})
const { result: toolResult } = await toolRes.json()
// toolResult.content[0].text === 'Hello, World!'

Notifications (no id field) receive a 204 No Content response:

await fetch('http://localhost:3000/mcp', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'notifications/initialized'
  })
})
// 204 No Content

SSE Transport (Legacy)

The MCP SSE transport is bidirectional. The client opens an SSE stream, receives a POST endpoint URL, then sends JSON-RPC requests to that URL. Responses and server notifications arrive on the SSE stream.

// 1. Open SSE connection
const events = new EventSource('http://localhost:3000/sse')

let messageEndpoint = null

// 2. Wait for the endpoint event (sent immediately on connect)
events.addEventListener('endpoint', (e) => {
  messageEndpoint = e.data
  // e.g. "http://localhost:3000/message?sessionId=client-1-1234567890"
})

// 3. Listen for responses and notifications on the SSE stream
events.addEventListener('message', (e) => {
  const msg = JSON.parse(e.data)

  if (msg.id) {
    // Response to a request you sent
    console.log('Response:', msg.result)
  } else if (msg.method) {
    // Server-initiated notification
    console.log('Notification:', msg.method, msg.params)
  }
})

// 4. Send JSON-RPC requests by POSTing to the endpoint
await fetch(messageEndpoint, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'tools/call',
    params: { name: 'greet', arguments: { name: 'World' } },
    id: 1
  })
})
// HTTP response is 202 Accepted — the actual result arrives on the SSE stream

WebSocket (Node.js only)

Full bidirectional JSON-RPC over WebSocket. Supports subscriptions and real-time notifications.

const ws = new WebSocket('ws://localhost:3000')

ws.onopen = () => {
  // Initialize
  ws.send(JSON.stringify({
    jsonrpc: '2.0',
    method: 'initialize',
    params: {
      protocolVersion: '2025-03-26',
      capabilities: {},
      clientInfo: { name: 'ws-client', version: '1.0.0' }
    },
    id: 1
  }))

  // Call a tool
  ws.send(JSON.stringify({
    jsonrpc: '2.0',
    method: 'tools/call',
    params: { name: 'greet', arguments: { name: 'World' } },
    id: 2
  }))

  // Subscribe to resource updates
  ws.send(JSON.stringify({
    jsonrpc: '2.0',
    method: 'resources/subscribe',
    params: { uri: 'stats://live' },
    id: 3
  }))
}

ws.onmessage = (e) => {
  const msg = JSON.parse(e.data)

  if (msg.type === 'connected') {
    // Initial connection status
    console.log('Connected as:', msg.clientId)
  } else if (msg.id) {
    // Response to a request
    console.log('Response:', msg.result)
  } else if (msg.method) {
    // Server notification (resource updates, progress, etc.)
    console.log('Notification:', msg.method, msg.params)
  }
}

Transport Return Object

createHttpTransport() returns:

Property	Type	Description
port	number	Bound port
host	string	Bound host
httpServer	http.Server	Underlying HTTP server
wss	WebSocketServer | null	WebSocket server (Node.js, if enabled)
wsClients	Map	Connected WebSocket clients
sseClients	Map	Connected SSE clients
activityLog	Array	Recent tool call activity
requestCount()	function	Returns total request count
broadcast(msg)	function	Send to all clients (WS + SSE)
close()	async function	Graceful shutdown

stdio Transport

For Claude Desktop and similar clients that communicate over stdin/stdout:

import { createMCPServer } from 'bare-mcp'
import { createStdioTransport } from 'bare-mcp/stdio'

const mcp = createMCPServer({ name: 'my-server', version: '1.0.0' })
mcp.addTool({ /* ... */ })

await createStdioTransport(mcp, {
  onActivity: (entry) => console.error('Tool:', entry.tool),
  onClose: () => process.exit(0)
})

Configuring MCP Clients

Claude Desktop (stdio)

~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/path/to/server.js"]
    }
  }
}

Claude Desktop (HTTP)

{
  "mcpServers": {
    "my-server": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

Cursor (HTTP)

In Cursor Settings → MCP, add the server URL:

http://localhost:3000/mcp

Cursor uses the Streamable HTTP transport (POST /mcp).

Generic MCP Client (HTTP)

Any MCP client that supports Streamable HTTP can connect by pointing at the /mcp endpoint:

http://your-host:3000/mcp

Clients that use the legacy SSE transport should connect to:

http://your-host:3000/sse

MCP Methods

Method	Description
initialize	Initialize connection, get capabilities
tools/list	List available tools
tools/call	Execute a tool
resources/list	List available resources
resources/templates/list	List resource templates
resources/read	Read a resource by URI
resources/subscribe	Subscribe to resource updates
resources/unsubscribe	Unsubscribe from updates
ping	Health check

Notification Types

Method	Description
notifications/resources/updated	A resource's content changed
notifications/resources/list_changed	Resources added/removed
notifications/tools/list_changed	Tools added/removed
notifications/progress	Progress update

API Reference

createMCPServer(options)

Create an MCP server instance.

const mcp = createMCPServer({
  name: 'my-server',           // Server name
  version: '1.0.0',            // Server version
  protocolVersion: '2025-11-25' // MCP protocol version
})

Returns an object with:

• addTool(tool) / addTools(tools[]) — Register tools
• addResource(resource) / addResources(resources[]) — Register resources
• addResourceTemplate(template) — Register URI template
• readResource(uri) — Read a resource
• notify(method, params) — Send notification
• notifyResourceUpdated(uri) — Notify resource changed
• notifyResourceListChanged() — Notify resources added/removed
• notifyToolListChanged() — Notify tools added/removed
• notifyProgress(token, progress, total?) — Send progress
• handleRequest(method, params) — Handle JSON-RPC request

createHttpTransport(mcp, options)

Start HTTP server with WebSocket and SSE support.

const transport = await createHttpTransport(mcp, {
  port: 3000,
  host: '0.0.0.0',
  websocket: true,
  onActivity: (entry) => {}
})

Returns:

• port, host — Bound address
• httpServer — Node.js HTTP server
• wss — WebSocket server
• broadcast(message) — Send to all clients
• close() — Shutdown server

createStdioTransport(mcp, options)

Start stdio transport for CLI usage.

const transport = await createStdioTransport(mcp, {
  onActivity: (entry) => {},
  onClose: () => {}
})

Bare Runtime (Pear)

This library uses which-runtime to automatically detect whether you're on Node.js or Bare and load the correct transport implementation. Your code is the same either way:

import { createMCPServer } from 'bare-mcp'
import { createHttpTransport } from 'bare-mcp/http'  // Auto-detects runtime
import { createStdioTransport } from 'bare-mcp/stdio'  // Auto-detects runtime

const mcp = createMCPServer({ name: 'my-app' })
mcp.addTool({ /* ... */ })

await createHttpTransport(mcp, { port: 3000 })

Explicit Imports

If you need to bypass runtime detection and target a specific implementation:

Transport	Node.js	Bare
HTTP	bare-mcp/http-node	bare-mcp/http-bare
stdio	bare-mcp/stdio-node	bare-mcp/stdio-bare

Transport Differences

	Node.js	Bare
HTTP	node:http + ws — Streamable HTTP, SSE, WebSocket	bare-http1 — Streamable HTTP, SSE (no WebSocket)
stdio	node:readline	Raw process.stdin/stdout

Dependencies

For Node.js:

npm install bare-mcp ws

For Bare/Pear:

npm install bare-mcp bare-http1

License

MIT