Skip to main content

MCP Framework

A framework for building Model Context Protocol (MCP) servers that can run on Cloudflare Workers (with native OAuth support) or as DXT (Claude Desktop Extension) files. Write your tools once, deploy everywhere.

Package: @alianzacap/mcp-framework Registry: GitHub Packages (@alianzacap scope) Current Version: 3.0.2

Framework Value​

  • Tool abstraction - Define once, deploy anywhere (Workers or stdio)
  • DXT automation - One command to build Claude Desktop extensions
  • Cross-platform - Same tools on edge and desktop

Installation​

npm install @alianzacap/mcp-framework

GitHub Packages Configuration​

Create or update your .npmrc file:

@alianzacap:registry=https://npm.pkg.github.com

Quick Start​

Creating a Cloudflare Worker MCP Server​

With Bearer Token Auth​

import { McpAgent } from 'agents/mcp';
import { createToolEntry } from '@alianzacap/mcp-framework';
import { z } from 'zod';

// Define tools using framework helpers
const echoDefinition = {
  name: 'echo',
  description: 'Echo back the provided message',
  inputSchema: z.object({
    message: z.string().describe('Message to echo back')
  })
};

const echoHandler = async ({ message }: { message: string }) => {
  return {
    content: [{ type: 'text' as const, text: `You said: ${message}` }]
  };
};

// Use native Agents SDK pattern
export class EchoMcpAgent extends McpAgent {
  async init() {
    const tools = [createToolEntry(echoDefinition, echoHandler)];

    for (const { definition, handler } of tools) {
      this.server.tool(
        definition.name,
        (definition.inputSchema as any)._def.shape(),
        handler
      );
    }
  }
}

With OAuth​

For user-facing MCP servers, use Cloudflare's native OAuth Provider:

npm install @cloudflare/workers-oauth-provider

See Cloudflare's MCP OAuth documentation.

DXT Extension Building​

Build Claude Desktop extensions with zero configuration:

{
  "scripts": {
    "build:dxt": "npm run build && node --input-type=module --eval \"import('@alianzacap/mcp-framework').then(f => f.buildDxtAuto())\""
  }
}

Manual DXT Configuration​

import { buildDxtAuto } from '@alianzacap/mcp-framework';

await buildDxtAuto({
  extensionName: 'my-custom-name',
  author: { name: 'Your Name', email: 'you@example.com' },
  userConfig: {
    API_KEY: {
      type: 'string',
      title: 'API Key',
      description: 'Your service API key',
      sensitive: true,
      required: true
    }
  }
});

API Reference​

Core Functions​

createMcpServer(config)​

Creates a new MCP server instance for stdio usage.

const server = createMcpServer({
  name: 'my-server',
  version: '1.0.0',
  tools
});

startStdioServer(server)​

Starts the server using stdio transport for command-line usage.

createToolEntry(definition, handler)​

Creates a tool entry for registration.

Cloudflare Worker Functions​

registerFrameworkTools(server, serverConfig)​

Register framework tools on an Agents SDK McpServer instance.

import { McpAgent } from 'agents/mcp';
import { registerFrameworkTools, createToolEntry } from '@alianzacap/mcp-framework';

export class MyAgent extends McpAgent {
  async init() {
    const tools = [createToolEntry(definition, handler)];
    registerFrameworkTools(this.server, {
      name: 'my-agent',
      version: '1.0.0',
      tools
    });
  }
}

Auth0 Integration​

JWT Validation:

import { validateAuth0Token } from '@alianzacap/mcp-framework/cloudflare';

const decoded = await validateAuth0Token(
  bearerToken,
  'dev-alianzacap.us.auth0.com',
  'urn:mcp-server'
);

M2M Handler for Hono:

import { createM2MHandlerForHono } from '@alianzacap/mcp-framework/cloudflare';

app.all("/mcp-m2m", createM2MHandlerForHono({
  agentClass: MyMcpAgent,
  validateToken: async (token, c) => {
    return await validateAuth0Token(token, c.env.AUTH0_DOMAIN, c.env.AUTH0_AUDIENCE);
  },
  validateTokenType: (decoded) => decoded.gty === 'client-credentials'
}));

Response Helpers​

import {
  createJsonResult,
  createErrorResult,
  validateRequiredArgs
} from '@alianzacap/mcp-framework';

// Success response
return createJsonResult({ data: 'value' });

// Error response
return createErrorResult('Something went wrong');

// Validate arguments
validateRequiredArgs(args, ['requiredField']);

Tool Definition Format​

import { z } from 'zod';
import { createToolEntry, createSuccessResult } from '@alianzacap/mcp-framework/cloudflare';

const weatherTool = createToolEntry(
  {
    name: 'getWeather',
    description: 'Get weather information for a location',
    inputSchema: z.object({
      location: z.string().describe('City name or coordinates'),
      units: z.enum(['celsius', 'fahrenheit']).optional()
    })
  },
  async ({ location, units = 'celsius' }) => {
    const weatherData = await getWeatherData(location, units);
    return createSuccessResult(
      `Weather in ${location}: ${weatherData.temperature}°`
    );
  }
);

Package Exports​

Main Export​

import {
  createMcpServer,
  startStdioServer,
  createToolEntry,
  createJsonResult,
  createErrorResult,
  validateRequiredArgs,
  convertZodSchemaToJsonSchema,
  buildDxtAuto,
  buildDxt,
  registerFrameworkTools
} from '@alianzacap/mcp-framework';

Cloudflare Export​

import {
  validateAuth0Token,
  createM2MHandlerForHono,
  createToolEntry,
  createJsonResult,
  createErrorResult
} from '@alianzacap/mcp-framework/cloudflare';
  • MCP JPPR - Puerto Rico property data server
  • MCP Baseline - Loan origination system server
  • MCP CRIM - CRIM cadastral data server
  • Source: mcp-framework/