futurity-mcp Library

futurity-mcp is a minimal MCP (Model Context Protocol) server library for Bun, making it easy to build custom integrations for Futurity.

Installation

bun add futurity-mcp

Quick Start

import { z } from "zod";
import { mcp } from "futurity-mcp";

const app = mcp({
  name: "my-server",
  version: "1.0.0",
});

app.tool("greet", {
  description: "Greet a user",
  input: z.object({
    name: z.string(),
  }),
  handler: async ({ name }) => {
    return { message: `Hello, ${name}!` };
  },
});

app.listen(3000);

Run it:

3000/mcp

bun run server.ts

API Reference

mcp(options)

Create an MCP application.

const app = mcp({
  name: "my-server",           // required
  version: "1.0.0",            // required
  path: "/mcp",                // default: "/mcp"
  instructions: "...",         // optional system instructions
  capabilities: { ... },       // optional MCP capabilities
});

Options:

Option	Type	Required	Description
name	string	Yes	Server name
version	string	Yes	Server version
path	string	No	MCP endpoint path (default: /mcp)
instructions	string	No	System instructions for AI
capabilities	object	No	MCP capabilities config
oauth	object	No	OAuth configuration
auth	function	No	Authentication middleware

app.tool(name, options)

Register a tool that Corint can use.

app.tool("add", {
  description: "Add two numbers",
  input: z.object({
    a: z.number(),
    b: z.number(),
  }),
  handler: async ({ a, b }) => {
    return { sum: a + b };
  },
});

Options:

Option	Type	Required	Description
description	string	Yes	What the tool does
input	ZodSchema	No	Input validation schema
handler	function	Yes	Implementation

Tool without input:

app.tool("ping", {
  description: "Health check",
  handler: async () => {
    return { status: "ok" };
  },
});

app.resource(uri, options)

Register a resource that provides data.

app.resource("config://settings", {
  description: "Application settings",
  fetch: async () => {
    return { theme: "dark", language: "en" };
  },
});

Options:

Option	Type	Required	Description
description	string	Yes	What the resource provides
fetch	function	Yes	Returns resource data

app.use(plugin)

Apply a plugin to the app.

import { cors } from "futurity-mcp";

app.use(
  cors({
    allowOrigin: "*",
    allowMethods: ["GET", "POST", "DELETE", "OPTIONS"],
  })
);

app.middleware(fn)

Add middleware directly.

app.middleware(async (req, next) => {
  console.log(`${req.method} ${req.url}`);
  return next(req);
});

app.listen(port, transport?)

Start the server.

// HTTP (default)
await app.listen(3000);

// WebSocket
await app.listen(3000, "websocket");

app.stop()

Stop the server.

await app.stop();

app.activeSessions

Get count of active sessions (HTTP transport).

console.log(app.activeSessions); // e.g., 5

CORS Configuration

import { mcp, cors } from "futurity-mcp";

const app = mcp({ name: "server", version: "1.0.0" });

app.use(
  cors({
    allowOrigin: "*",                // or specific origin
    allowMethods: ["GET", "POST", "DELETE", "OPTIONS"],
    allowHeaders: ["Content-Type", "Authorization", "Accept", "Mcp-Session-Id"],
    exposeHeaders: ["Mcp-Session-Id"],
    maxAge: 86400,
    credentials: false,
  })
);

app.listen(3000);

OAuth Configuration

Configure OAuth metadata for /.well-known/oauth-authorization-server:

const app = mcp({
  name: "server",
  version: "1.0.0",
  oauth: {
    issuer: "https://auth.example.com",
    authorizationEndpoint: "https://auth.example.com/oauth/authorize",
    tokenEndpoint: "https://auth.example.com/oauth/token",
    jwksUri: "https://auth.example.com/.well-known/jwks.json",
    scopesSupported: ["openid", "profile"],
  },
});

Custom Authentication

const app = mcp({
  name: "server",
  version: "1.0.0",
  auth: async (req) => {
    const token = req.headers.get("authorization")?.replace("Bearer ", "");
    if (!token) return false;
    return await validateToken(token);
  },
});

Stateful Patterns

State is shared across all sessions:

const state = {
  counter: 0,
  items: new Map<string, string>(),
};

app.tool("increment", {
  description: "Increment the counter",
  handler: async () => {
    state.counter++;
    return { counter: state.counter };
  },
});

app.tool("set", {
  description: "Set a key-value pair",
  input: z.object({ key: z.string(), value: z.string() }),
  handler: async ({ key, value }) => {
    state.items.set(key, value);
    return { key, value };
  },
});

app.tool("get", {
  description: "Get a value by key",
  input: z.object({ key: z.string() }),
  handler: async ({ key }) => {
    return { value: state.items.get(key) ?? null };
  },
});

Multi-Session Support

The HTTP transport supports multiple concurrent client sessions:

const app = mcp({ name: "server", version: "1.0.0" });

// Tools and resources are registered once, replicated per session
app.tool("example", {
  description: "Example tool",
  handler: async () => ({ ok: true })
});

await app.listen(3000);

// Check active sessions
console.log(app.activeSessions);

// Stop server
await app.stop();

Direct Transport Usage

For advanced use cases, use transports directly:

import { StreamableHttpServer, StreamableHttpTransport } from "futurity-mcp";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

const server = new StreamableHttpServer({
  port: 3000,
  path: "/mcp",
  onSession: async (transport: StreamableHttpTransport) => {
    const mcp = new McpServer({ name: "server", version: "1.0.0" });
    // register tools on mcp...
    await mcp.connect(transport);
  },
});

await server.start();

TypeScript Types

import type {
  McpApp,
  McpAppOptions,
  ToolOptions,
  ResourceOptions,
  Middleware,
  AuthMiddleware,
  StreamableHttpServer,
  StreamableHttpServerOptions,
  StreamableHttpTransport,
  WebSocketTransport,
  WebSocketTransportOptions,
} from "futurity-mcp";

Testing Your Server

Use the discovery CLI to test your implementation:

bun run discover http://localhost:3000/mcp

Next Steps

• Building MCP servers guide
• Custom integrations