Getting Started

Build your first MCP server using the TypeScript template. Learn core concepts while creating real tools that AI agents can use.

What We'll Build

By the end of this guide, you'll have a fully functional MCP server with:

  • 🧰 Custom Tools: Functions that AI agents can call
  • 📚 Resources: Data sources agents can read
  • 💭 Prompts: Reusable prompt templates
  • 🌐 WebSocket & SSE Support: Real-time communication protocols
  • 🚀 Cloudflare Deployment: Production-ready hosting

Quick Setup

1. Initialize Your Project

bash

This creates:

  • mcp.json - MCP server configuration
  • Adds dev:nullshot script to package.json
  • Adds postinstall script for automatic dependency management
  • Optionally configures cf-typegen for Cloudflare Workers types

2. Configure Your Services

Edit the generated mcp.json with the TypeScript MCP template:

json

3. Install Dependencies

bash

This will:

  • Install packages from GitHub repositories
  • Detect and extract Cloudflare Workers configurations
  • Run D1 database migrations if present
  • Generate service bindings in your wrangler.jsonc
  • Generate Cloudflare Workers types with cf-typegen

5. Start Development

bash

6. Start MCP Inspector

bash

The MCP Inspector will automatically open at http://localhost:6274 and your MCP server will run on http://localhost:8787. The Inspector should automatically connect using SSE transport at http://localhost:8787/sse.

Understanding the Architecture

Project Structure

code

Core Implementation

1. Main Entry Point (src/index.ts)

The entry point handles routing and protocol negotiation:

typescript

The above forwards requets to a dedicated MCP server which supports the following with zero configuration:

Key Features:

  • Health Check: Simple endpoint to verify server status
  • WebSocket Support: Real-time bidirectional communication
  • SSE Support: Server-sent events for streaming responses
  • Durable Objects: Persistent, stateful server instances

2. MCP Server Implementation (src/server.ts)

The server extends our MCP framework and configures tools, resources, and prompts:

typescript

Key Concepts:

  • Implementation: Metadata about your MCP server
  • Tools: Functions that agents can execute
  • Resources: Data sources agents can access
  • Prompts: Reusable prompt templates

3. Building Your First Tool (src/tools.ts)

Tools are functions that AI agents can call. Here's a simple "Hello World" example:

typescript

Tool Development Best Practices:

  1. Clear Naming: Use descriptive, hyphenated names
  2. Rich Descriptions: Help AI understand when to use your tool
  3. Schema Validation: Use Zod for type-safe parameter validation
  4. Error Handling: Provide helpful error messages
  5. Structured Output: Return consistent response formats

4. Adding Resources (src/resources.ts)

Resources are data sources that agents can read:

typescript

5. Creating Prompts (src/prompts.ts)

Prompts are reusable templates that help AI agents:

typescript

Test locally

  1. run pnpm run dev
  2. Go to the http://localhost:6724 and enter in the mcp server http://localhost:8787/sse and start testing with MCP Inspector

Deployment to Production

1. Deploy to Cloudflare

bash

2. Use Your MCP Server

Once deployed, your MCP server will be available at:

  • WebSocket: wss://your-worker.workers.dev/ws
  • SSE: https://your-worker.workers.dev/sse

Next Steps

Expand Your Server

  1. Add More Tools: Create tools for file operations, API integrations, calculations
  2. Dynamic Resources: Connect to databases, APIs, or file systems
  3. Advanced Prompts: Create domain-specific prompt templates
  4. Error Handling: Implement robust error handling and retries

Integration Examples

typescript

Advanced Patterns

  • Stateful Tools: Use Durable Objects for persistent state
  • Streaming Tools: Implement real-time data streams
  • Composite Tools: Chain multiple operations together
  • Authenticated Tools: Add authentication and authorization

Resources

🎉 Congratulations! You've built your first MCP server. Your tools are now ready to be used by AI agents across any platform that supports the Model Context Protocol.