Development Guide

Learn how to develop, build, and test your MCP servers with ModelFetch's powerful development tools and workflow.

Development Server

The development server provides live reload, automatic TypeScript compilation, and real-time testing capabilities for your MCP server.

npm run dev

Development server features:

Automatic TypeScript compilation
Live reload on file changes
Real-time error reporting
Source map support for debugging
ESM module bundling

The development server runs your MCP server in a local environment where you can test and debug your tools before deployment. Any changes to your source code will automatically restart the server.

Building Your MCP Server

Build your MCP server for production or testing with the build command:

npm run build

This creates an optimized, minified bundle in the dist/ directory:

dist/
├── index.js              # Your bundled MCP server
├── index.js.map          # Source map for debugging
└── __modelfetch__.js     # ModelFetch runtime loader

Build optimizations:

Code minification and tree shaking
External Node.js modules are excluded
TypeScript compilation with type checking
ESM format for modern environments
Source maps for production debugging

Writing MCP Tools

MCP tools are the core functionality of your server. Here's how to create them:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

export default function createMcpServer({ implementation }: Options) {
  const mcpServer = new McpServer(implementation);

  // Simple tool with no parameters
  mcpServer.tool(
    "get_current_time",
    "Gets the current time",
    {},
    () => {
      const now = new Date().toISOString();
      return {
        content: [{
          type: "text",
          text: `Current time: ${now}`
        }]
      };
    }
  );

  // Tool with parameters and validation
  mcpServer.tool(
    "calculate_circle_area",
    "Calculates the area of a circle",
    {
      radius: z.number().positive().describe("Radius of the circle")
    },
    ({ radius }) => {
      const area = Math.PI * radius * radius;
      return {
        content: [{
          type: "text",
          text: `Area of circle with radius ${radius}: ${area.toFixed(2)}`
        }]
      };
    }
  );

  // Tool with complex input validation
  mcpServer.tool(
    "send_email",
    "Sends an email",
    {
      to: z.string().email().describe("Recipient email address"),
      subject: z.string().min(1).describe("Email subject"),
      body: z.string().describe("Email body content"),
      priority: z.enum(["low", "normal", "high"]).default("normal")
    },
    async ({ to, subject, body, priority }) => {
      // Your email sending logic here
      await sendEmail({ to, subject, body, priority });

      return {
        content: [{
          type: "text",
          text: `Email sent successfully to ${to}`
        }]
      };
    }
  );

  return mcpServer;
}

Tool best practices:

Use descriptive tool names and descriptions
Validate input parameters with Zod schemas
Handle errors gracefully and return meaningful messages
Use async/await for asynchronous operations
Return structured content with appropriate types

Type System: The Options type and other ModelFetch types are automatically available through the triple-slash reference /// <reference types="@modelfetch/node" /> in your src/env.d.ts file. This eliminates the need to explicitly import types in your implementation files.

Testing Your MCP Server

There are several ways to test your MCP server during development:

Local Testing with AI Clients

Start your MCP server locally (either in development or production mode) and connect it to AI clients for testing:

# Development mode (with live reload)
npm run dev

# OR production mode (build first, then run)
npm run build
npm start

# Your MCP server runs on port 33333 (default) and is ready for connections

Once your MCP server is running locally, you can connect it to AI clients that support MCP servers. Here are some popular options:

MCP Inspector (recommended)

A dedicated testing tool for MCP servers with a graphical interface.

npx -y @modelcontextprotocol/inspector@latest

Cursor

Add to your Cursor MCP configuration file:

{
  "mcpServers": {
    "my-mcp-server": {
      "url": "http://localhost:33333/mcp"
    }
  }
}

Windsurf

Add to your Windsurf MCP configuration file:

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

VS Code

Add to your VS Code MCP configuration file:

"mcp": {
  "servers": {
    "my-mcp-server": {
      "type": "http",
      "url": "http://localhost:33333/mcp"
    }
  }
}

Claude Desktop

Add to your Claude Desktop configuration file:

{
  "mcpServers": {
    "my-mcp-server": {
      "url": "http://localhost:33333/mcp"
    }
  }
}

Connection: All clients connect to your running MCP server via http://localhost:33333/mcp. Some older MCP clients only support the SSE protocol, if your client doesn't work with /mcp, try using /sse instead. Make sure your MCP server is running before connecting the AI clients. If you've configured a different port using the PORT environment variable, update the URL accordingly.

Available Scripts

Your MCP server project comes with these npm scripts:

Script	Command	Description
`npm run deploy`	`modelfetch deploy`	Deploy to ModelFetch platform
`npm run dev`	`modelfetch dev`	Start development server
`npm run build`	`modelfetch build`	Build production server
`npm start`	`node dist/__modelfetch__.js`	Run the production server locally

Environment Variables

Use environment variables for configuration that changes between environments:

// In your MCP server code
const apiKey = process.env.API_KEY;
const dbUrl = process.env.DATABASE_URL;

if (!apiKey) {
  throw new Error("API_KEY environment variable is required");
}

Create a .env file for local development:

API_KEY=your_api_key_here
DATABASE_URL=postgresql://localhost:5432/mydb

Security: Never commit .env files or sensitive credentials to version control. Use environment variables for production deployment.

Next Steps

Now that you understand the development workflow, you can:

Build and test your MCP server tools locally
Connect your server to AI clients for integration testing
Deploy your MCP server to production when you're ready
Explore the full CLI reference for advanced usage

Ready to ship? Your development workflow is complete! Test your MCP server thoroughly with AI clients, then deploy to production when you're confident in your implementation.