bun-mcp-server

A white-label HTTP-based Model Context Protocol (MCP) server built with Bun.

Motivation

This project began as a personal learning exercise to better understand how MCP servers work by building one from the ground up. As such, it currently implements a meaningful subset of the MCP specification, with compliance support being added over time as the project evolves.

You can read the full MCP specification here.

Features

• White-label Config — Server identity (name, title, description, version, categories) is controlled entirely from a single mcp.config.js file.
• Auto Tool Discovery — Tools placed in the tools/ directory are loaded and registered automatically at startup — no manual wiring required.
• HTTP Transport — Serves MCP over a standard HTTP endpoint (/mcp), supporting POST, GET, DELETE, and OPTIONS.
• JSON-RPC 2.0 — Fully compliant request/response framing with proper error codes (-32700, -32600, -32601, -32602, -32603).
• Session Management — Issues an mcp-session-id on initialize, tracks sessions in memory, and automatically expires them after 5 minutes of inactivity.
• Protocol Version Enforcement — Validates the mcp-protocol-version header on every non-initialization request.
• Origin-aware CORS — Reflects the request Origin header and exposes mcp-session-id and mcp-protocol-version to browser clients.

Quick Start

Install dependencies

bun install

Start the server

bun run dev

The server starts on http://localhost:3000 with file-watching enabled for live reload during development.

White-labeling

Clone the repo, edit the config, add your tools. Follow the steps below to get started.

Step 1 — Configure your identity

Open mcp.config.js and update the following values:

export const config = {
  name: "my-mcp-server",         // Machine-readable identifier (used in client configs)
  title: "My MCP Server",        // Human-readable display name
  description: "Does something useful.",
  version: "1.0.0",
  protocolVersion: "2025-11-25", // MCP spec version this server targets
  categories: ["demo"],          // Descriptive tags for discoverability
}

These values flow into two places automatically:

• The `initialize` response — returned to any MCP client during the handshake
• The Server Card at GET /.well-known/mcp — used for server discovery

Step 2 — Add your tools

Drop .js files into the tools/ directory. The server loads them automatically at startup — no registration needed. See Tools for the file format.

Step 3 — Announce your server

Once running, your server self-describes via the /.well-known/mcp endpoint — the MCP Server Card. This gives clients a machine-readable way to discover your server's identity, transport type, and endpoint URL without any manual configuration.

curl http://localhost:3000/.well-known/mcp

{
  "name": "my-mcp-server",
  "title": "My MCP Server",
  "description": "Does something useful.",
  "version": "1.0.0",
  "url": "http://localhost:3000/mcp",
  "transport": "http",
  "categories": ["demo"]
}

[!Note] The /.well-known/mcp Server Card is not yet part of the official MCP specification, but it fills a gap: there is currently no standardized way for HTTP-based MCP servers to announce themselves. This endpoint follows the established /.well-known/ convention for service discovery on the web.

Tools

Available Tools

The get_weather tool returns simulated data (random temperature, "Cloudy" condition) — it is included as a demo tool for testing the MCP lifecycle.

Adding New Tools

Drop a new .js file into the tools/ directory. The server picks it up automatically at startup.

Each tool file must export two things:

`metadata` — the tool's schema (name, description, input shape):

export const metadata = {
  name: "my_tool",
  title: "My Tool",
  description: "Does something useful.",
  parameters: {
    type: "object",
    properties: {
      input: { type: "string", description: "Some input value" }
    },
    required: ["input"]
  }
}

`handler` — an async function that receives the tool's arguments:

export async function handler({ input }) {
  // Your tool logic here
  return { result: `Processed: ${input}` }
}

The tool is automatically available via tools/list and executable via tools/call — no additional wiring needed.

See tools/get_weather.js for a working example.

Project Structure

bun-mcp-server/
├── src/
│   ├── index.js          # Entry point — starts the Bun HTTP server and runs session cleanup
│   ├── lib/
│   │   ├── sessions.js   # In-memory session store (Map)
│   │   └── utils.js      # Shared utilities (timestamps, CORS headers, logging, IP parsing)
│   ├── mcp/
│   │   ├── index.js      # Core MCP request handler (JSON-RPC dispatch)
│   │   └── tools.js      # Auto-loads tools from the tools/ directory
│   └── routes/
│       └── index.js      # HTTP route definitions (/mcp, /.well-known/mcp, catch-all)
├── tools/                # Drop tool files here — they are picked up automatically
│   └── get_weather.js    # Example tool (simulated weather data)
├── mcp.config.js         # Server identity and capabilities config
├── package.json
└── jsconfig.json

Prerequisites

• Bun v1.3+ installed

API Reference

POST /mcp

The main MCP endpoint. Accepts JSON-RPC 2.0 requests and dispatches them to the appropriate handler.

For all methods except initialize and notifications, the request must include:

• mcp-session-id header — a valid session ID issued during initialize
• mcp-protocol-version header — must match the server's configured protocol version

Supported methods:

GET /mcp

Session probe. Requires a valid mcp-session-id header. Returns 200 if the session exists, 404 if not. Returns 406 if the client requests text/event-stream (SSE is not currently supported).

DELETE /mcp

Session termination. Requires a valid mcp-session-id header. Removes the session and returns 204.

OPTIONS /mcp

CORS preflight. Returns 204 with appropriate Access-Control-* headers.

GET /.well-known/mcp

See Step 3 — Announce your server above.

* /*

Catch-all route that returns a 404 Not Found JSON response for any unmatched path.

Usage Examples

Initialize the server

On success, the server returns an mcp-session-id header. Save it — all subsequent requests must include it.

curl -D - -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-11-25",
      "capabilities": {},
      "clientInfo": { "name": "test-client", "version": "1.0.0" }
    }
  }'

List available tools

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: <your-session-id>" \
  -H "mcp-protocol-version: 2025-11-25" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list"
  }'

Call a tool

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: <your-session-id>" \
  -H "mcp-protocol-version: 2025-11-25" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "get_weather",
      "arguments": { "city": "Tokyo" }
    }
  }'

Terminate a session

curl -X DELETE http://localhost:3000/mcp \
  -H "mcp-session-id: <your-session-id>"

Connecting a Client

You can verify that the server is functioning correctly by connecting it to an MCP client, such as VS Code or AntiGravity.

[!Note] Ensure your MCP server is already running locally before connecting. Upon success, you will see connection activity in your server's console logs.

VS Code

1. Create or open .vscode/mcp.json in your project directory.
2. Add the following entry:

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

1. In the VS Code Chat panel, click the gear icon to open the Agent Customizations dialog.
2. Select MCP Servers from the sidebar. You should see my-mcp-server listed under Workspace.
3. Right-click my-mcp-server and select Start Server from the context menu to initialize the connection.

AntiGravity

1. Open Configuration: Navigate to Additional Options (...) and select MCP Servers.
2. Manage Servers: Click Manage MCP Servers, then select View raw config to open the mcp_config.json file.
3. Add Server: Add the following configuration:

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

1. Connect: Save the file, return to the Manage MCP Servers menu, and click Refresh.

Once connected, confirm that tool discovery and execution are working by sending a prompt through your IDE's chat interface:

"Let's test the MCP server. Get the weather for Tokyo today."

If successful, the chat should trigger the tool and return the relevant data from your server.

Error Handling

The server returns standard JSON-RPC 2.0 error responses:

Musings & Future Direction

2026-07-01 — Streamable HTTP

The MCP specification defines Streamable HTTP as one of the supported transport mechanisms for MCP servers. It replaces the HTTP+SSE transport used in earlier versions of the protocol.

I haven't implemented Streamable HTTP in this project yet, as I'm still learning how it works. Support for it will be added in the future, hopefully.

2026-06-30 - MCP Server Card

The idea is to introduce an MCP Server Card, similar to the Web App Manifest for web applications. A Server Card would provide standardized metadata that serves as the foundation for searchable directories of MCP servers, making it easy for users to discover and add servers to their MCP clients or IDEs. That’s the dream, at least.

License

MIT © supershaneski