Custom MCP Servers

Build custom integrations for Futurity using the Model Context Protocol (MCP). MCP allows you to create tools that Corint can use to interact with any external service.

What is MCP?

MCP (Model Context Protocol) is a standardized way to:

Expose tools to AI assistants
Provide resources and data
Handle authentication
Manage sessions

When you build an MCP server, Corint can use your custom tools just like built-in capabilities.

Use Cases

Build MCP servers to:

Connect proprietary systems: Internal APIs, databases, services
Extend capabilities: Custom tools specific to your domain
Integrate third-party services: Any API that doesn’t have native integration
Automate workflows: Complex operations as single tools

Getting Started

Futurity provides futurity-mcp, a minimal MCP server library for Bun.

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);

bun run server.ts

Creating Tools

Basic Tool

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

Tool Without Input

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

Tool Descriptions

Good descriptions help Corint understand when to use your tool:

app.tool("search_customers", {
  description: `Search for customers by name or email.
    Use this when the user asks to find a customer
    or look up customer information.`,
  input: z.object({
    query: z.string().describe("Name or email to search for"),
    limit: z.number().default(10).describe("Maximum results"),
  }),
  handler: async ({ query, limit }) => {
    // ... implementation
  },
});

Creating Resources

Resources provide data that Corint can access:

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

Authentication

OAuth Support

Configure OAuth for user authentication:

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 Auth Middleware

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);
  },
});

Middleware

Adding Middleware

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

CORS

import { cors } from "futurity-mcp";

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

Transport Options

HTTP (Default)

await app.listen(3000);

WebSocket

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

Stateful Patterns

Maintain state across requests:

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

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

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

app.tool("get", {
  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" });

app.tool("example", { handler: async () => ({ ok: true }) });

await app.listen(3000);

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

// Stop server
await app.stop();

Connecting to Futurity

Registering Your MCP Server

Deploy your MCP server to a publicly accessible URL
Ensure HTTPS is configured
Contact support with your server URL and configuration
We’ll validate and enable the integration

Testing Locally

Test your MCP server before deploying:

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

Best Practices

Tool Design

Single responsibility: Each tool does one thing well
Clear descriptions: Help Corint understand when to use it
Validate inputs: Use Zod schemas for type safety
Handle errors: Return meaningful error messages

Security

Authenticate all requests: Don’t expose unprotected endpoints
Validate tokens: Check signatures and expiration
Rate limit: Prevent abuse
Log access: Maintain audit trails

Performance

Keep tools fast: Under 30 seconds ideally
Cache when possible: Reduce external API calls
Handle timeouts: Set reasonable timeouts for external calls

Examples

Find example MCP servers in the repository:

bun examples/cors.ts         # CORS configuration
bun examples/oauth.ts        # OAuth metadata
bun examples/stateful.ts     # Counter, notes, key-value store
bun examples/todo-app.ts     # Todo list with CRUD and filtering
bun examples/calculator.ts   # Math operations and unit conversion
bun examples/filesystem.ts   # Virtual filesystem
bun examples/weather-api.ts  # Weather data API
bun examples/database.ts     # Document database
bun examples/monday.ts       # monday.com integration