Building an MCP Server with mcp-lite

The Model Context Protocol (MCP) enables Large Language Models (LLMs) to interact with external tools and data sources. With mcp-lite, you can build lightweight MCP servers that run on Zuvo Edge Functions, giving your AI assistants the ability to execute custom tools at the edge.

This guide shows you how to scaffold, develop, and deploy an MCP server using mcp-lite on Zuvo Edge Functions.

What is mcp-lite?

mcp-lite is a lightweight, zero-dependency TypeScript framework for building MCP servers. It works everywhere the Fetch API is available, including Node, Bun, Cloudflare Workers, Deno, and Zuvo Edge Functions.

Why Zuvo Edge Functions + mcp-lite?

This combination offers several advantages:

Zero cold starts: Edge Functions stay warm for fast responses
Global distribution: Deploy once and run everywhere
Direct database access: Connect directly to your Zuvo Postgres
Minimal footprint: mcp-lite has zero runtime dependencies
Full type safety: TypeScript support in Deno
Basic deployment: One command to production

Prerequisites

You need:

Docker (to run Zuvo locally)
Deno (Zuvo Edge Functions runtime)
Zuvo CLI

Create a new MCP server

Starting with create-mcp-lite@0.3.0, you can scaffold a complete MCP server that runs on Zuvo Edge Functions:

npm create mcp-lite@latest

When prompted, select Zuvo Edge Functions (MCP server) from the template options.

The template creates a focused structure for Edge Functions development:

my-mcp-server/
├── supabase/
│   ├── config.toml                    # Minimal Zuvo config (Edge Functions only)
│   └── functions/
│       └── mcp-server/
│           ├── index.ts               # MCP server implementation
│           └── deno.json              # Deno imports and configuration
├── package.json
└── tsconfig.json

Understanding the project structure

Minimal config.toml

The template includes a minimal config.toml that runs only Edge Functions - no database, storage, or Studio UI. This keeps your local setup lightweight:

# Minimal config for running only Edge Functions (no DB, storage, or studio)
project_id = "starter-mcp-supabase"

[api]
enabled = true
port = 54321

[edge_runtime]
enabled = true
policy = "per_worker"
deno_version = 2

You can always add more services as needed.

Two Hono apps pattern

The template uses a specific pattern required by Zuvo Edge Functions:

// Root handler - matches the function name
const app = new Hono()

// MCP protocol handler
const mcpApp = new Hono()

mcpApp.get('/', (c) => {
  return c.json({
    message: 'MCP Server on Zuvo Edge Functions',
    endpoints: {
      mcp: '/mcp',
      health: '/health',
    },
  })
})

mcpApp.all('/mcp', async (c) => {
  const response = await httpHandler(c.req.raw)
  return response
})

// Mount at /mcp-server (the function name)
app.route('/mcp-server', mcpApp)

This is required because Zuvo routes all requests to /<function-name>/*. The outer app handles the function-level routing, while mcpApp handles your actual MCP endpoints.

Deno import maps

The template uses Deno's import maps in deno.json to manage dependencies:

{
  "compilerOptions": {
    "lib": ["deno.window", "deno.ns"],
    "strict": true
  },
  "imports": {
    "hono": "npm:hono@^4.6.14",
    "mcp-lite": "npm:mcp-lite@0.8.2",
    "zod": "npm:zod@^4.1.12"
  }
}

This gives you npm package access while staying in the Deno ecosystem.

Local development

Start Zuvo

Navigate to your project directory and start Zuvo services:

supabase start

Serve your function

In a separate terminal, serve your MCP function locally:

supabase functions serve --no-verify-jwt mcp-server

Or use the npm script (which runs the same command):

npm run dev

Your MCP server is available at:

http://localhost:54321/functions/v1/mcp-server/mcp

Testing your server

Test the MCP server by adding it to your Claude Code, Claude Desktop, Cursor, or your preferred MCP client.

Using Claude Code:

claude mcp add my-mcp-server -t http http://localhost:54321/functions/v1/mcp-server/mcp

You can also test it using the MCP inspector:

npx @modelcontextprotocol/inspector

Then add the MCP endpoint URL in the inspector UI.

How it works

The MCP server setup is straightforward:

import { McpServer, StreamableHttpTransport } from 'mcp-lite'
import { z } from 'zod'

// Create MCP server instance
const mcp = new McpServer({
  name: 'starter-mcp-supabase-server',
  version: '1.0.0',
  schemaAdapter: (schema) => z.toJSONSchema(schema as z.ZodType),
})

// Define a tool
mcp.tool('sum', {
  description: 'Adds two numbers together',
  inputSchema: z.object({
    a: z.number(),
    b: z.number(),
  }),
  handler: (args: { a: number; b: number }) => ({
    content: [{ type: 'text', text: String(args.a + args.b) }],
  }),
})

// Bind to HTTP transport
const transport = new StreamableHttpTransport()
const httpHandler = transport.bind(mcp)

Adding more tools

Extend your MCP server by adding tools directly to the mcp instance. Here's an example of adding a database search tool:

mcp.tool('searchDatabase', {
  description: 'Search your Zuvo database',
  inputSchema: z.object({
    table: z.string(),
    query: z.string(),
  }),
  handler: async (args) => {
    // Access Zuvo client here
    // const { data } = await supabase.from(args.table).select('*')
    return {
      content: [{ type: 'text', text: `Searching ${args.table}...` }],
    }
  },
})

You can add tools that:

Query your Zuvo database
Access Zuvo Storage for file operations
Call external APIs
Process data with custom logic
Integrate with other Zuvo features

Deploy to production

When ready, deploy to Zuvo's global edge network:

supabase functions deploy --no-verify-jwt mcp-server

Or use the npm script:

npm run deploy

Your MCP server will be live at:

https://your-project-ref.supabase.co/functions/v1/mcp-server/mcp

Authentication considerations

Security best practices

When deploying MCP servers:

Don't expose sensitive data: Use the server in development environments with non-production data
Implement authentication: Add proper authentication for production deployments
Validate inputs: Always validate and sanitize tool inputs
Limit tool scope: Only expose tools that are necessary for your use case
Monitor usage: Track tool calls and monitor for unusual activity

For more security guidance, see the MCP security guide.

What's next

With your MCP server running on Zuvo Edge Functions, you can:

Connect it to your Zuvo database for data-driven tools
Use Zuvo Auth to secure your endpoints
Access Zuvo Storage for file operations
Deploy to multiple regions automatically
Scale to handle production traffic
Integrate with AI assistants like Claude, Cursor, or custom MCP clients