TypeScript MCP Workshop: Complete Guide to Local and Remote Servers

Model Context Protocol (MCP) is an open protocol that enables language models and AI systems to dynamically discover, describe, and interact with external tools, APIs, and services in a standardised way. MCP allows for flexible, real-time tool integration, making it possible for AI to adapt to new capabilities without redeployment.

This workshop demonstrates both local and remote MCP implementations using TypeScript, progressing from basic concepts to production-ready servers that work with Claude, ChatGPT, and other MCP clients.

Prerequisites

The workshop requires the following tools to be installed:

• Node.js v22 or higher
• pnpm (Package manager)
• TypeScript configuration (provided in the repo)

LLM Configuration

You can use the examples with ollama and models like llama3.2:latest, but for better results use frontier models from OpenAI, Anthropic, Google, Mistral, or Groq.

Update the model variable in src/model.ts to configure your preferred model.

Setup and Environment Check

Run the setup script to verify your environment is properly configured:

pnpm setup

This will run the setup script located at scripts/setup.js. You can review or run this script directly if you want to see exactly what is being checked or to troubleshoot your environment.

The setup script will:

1. Check Node.js version (v22+ required)
2. Verify package manager installation
3. Check Ollama installation and required models
4. Validate TypeScript configuration
5. Test network connectivity for remote examples

Examples Overview

Part I: Local MCP Servers

These examples demonstrate MCP servers running locally, perfect for learning core concepts and local AI workflows.

01 - Tools Only

A dynamic calculator server that demonstrates how to add, remove, and discover tools at runtime using MCP. Learn how to build and test tools that can be updated live, with no server restart required.

# Run server
pnpm example:server:01

# Run client
pnpm example:client:01

02 - Resources: Give AI Access to Real Data

Serve live data, files, and documentation to AI using MCP resources. This example shows how to expose system metrics, logs, configurations, and more, in multiple formats (JSON, CSV, HTML, images).

# Run server
pnpm example:server:02

# Run client
pnpm example:client:02

03 - Prompts: Consistent AI Results

Build a library of reusable prompt templates for consistent, high-quality AI results. See how to generate code reviews, team discussions, explanations, and more, using dynamic prompt construction.

# Run server
pnpm example:server:03

# Run client
pnpm example:client:03

04 - Standard I/O and Filesystem

Use the stdio protocol to enable local MCP servers to access your filesystem. Expose tools for listing directories and reading files, and see how local AI tools can interact with your real environment.

# Run server
pnpm example:server:04

# Run client
pnpm example:client:04

05 - Multi-Server Architecture

Compose multiple MCP servers (e.g., user and payment services) and combine their tools in a single client workflow. Demonstrates modular, scalable AI architectures.

# Run both user and payment servers
pnpm example:server:05

# Run client
pnpm example:client:05

06 - Authentication with API Keys

Implement API key authentication and session management in MCP servers. Learn how to restrict access, personalize responses, and audit user actions for secure, stateful AI workflows.

# Run server
pnpm example:server:06

# Run client with API key
pnpm example:client:06 -- --api-key your-key-here

07 - Playwright Demo: Browser Automation

Automate browsers using Playwright and MCP. This demo shows how to expose Playwright's browser automation capabilities as MCP tools, enabling an AI to navigate websites, fill forms, scrape data, and take screenshots.

# Run client
pnpm example:client:07

Part II: Remote MCP Servers (Production-Ready)

These examples demonstrate remote MCP servers that work with Claude, ChatGPT, and other MCP clients over HTTP, including all production requirements.

08 - Remote Server Fundamentals

Learn the fundamental differences between local and remote MCP servers. Implement your first HTTP-based MCP server with proper transport handling, session management, and basic error handling.

Key Concepts: HTTP transports, session IDs, JSON-RPC over HTTP, basic server setup

# Run remote server
pnpm example:server:08

# Test with MCP Inspector or curl
pnpm inspect:08

09 - OAuth 2.1 Authentication

Implement complete OAuth 2.1 authentication with PKCE flow as required by the MCP specification. Includes all discovery endpoints, client registration, and secure token handling.

Key Concepts: OAuth 2.1, PKCE flow, .well-known endpoints, client registration, token validation

# Run OAuth-enabled server
pnpm example:server:09

# Test OAuth flow
pnpm example:client:09

Debugging with MCP Inspector

The MCP Inspector is a powerful tool for interactively testing and debugging your MCP servers:

# Inspect any example server
pnpm inspect

# Inspect specific examples
pnpm inspect:01  # Local tools-only

Next Steps

1. Start with Local Examples (01-07) if you're new to MCP
2. Move to Remote Examples (08-09) for production use cases

Each example builds on previous concepts while introducing new functionality, ensuring you understand both the fundamentals and advanced production requirements.

---

For detailed information about each example, see the individual README files in each directory.