Mastra MCP Workshop: Best Practices

A hands-on workshop demonstrating MCP (Model Context Protocol) best practices using Mastra. Build a "Customer Analytics" MCP server that showcases workflow-oriented tools, authentication patterns, and multi-system integration.

🎯 Workshop Goals

• Minimize surface area: 2 tools that handle many use cases
• Workflow-shaped tools: Capabilities (explore schema, run queries) vs endpoints (getUsers)
• Model compatibility: Test with multiple models, ensure consistent behavior
• Exploration: Let AI discover capabilities through resources
• Guardrails: Safe, deterministic, read-only by default

🏗️ What We'll Build

Customer Analytics MCP Server featuring:

• 📊 2 Tools: compute_account_health (multi-system workflow), run_sql (database queries)
• 📚 1 Resource: schema://main (discovery & exploration)
• 🔄 Workflow Patterns: External API integration, data fusion, scoring algorithms
• 🛡️ Built-in Safety: SELECT-only, implicit LIMIT, parsed queries, API rate limits
• 🔐 Authentication: Transparent role-based access control (admin/user/readonly)

🚀 Quick Start

Prerequisites

# Required
node >= 20.9.0
pnpm >= 8.0.0

# Optional: OpenAI API key for demo
export OPENAI_API_KEY="your-key-here"

Installation

# Clone and install
git clone <this-repo>
cd mcp-server-workshop-best-practices
pnpm install

# Terminal 1: Start HTTP MCP server with real auth
pnpm mcp-http-server

# Terminal 2: Run HTTP workshop demo
pnpm workshop-demo-http

# Server runs on http://localhost:3001 with endpoints:
# - /mcp (MCP endpoint with auth)
# - /health (health check)

🛠️ Technical Deep Dive

MCP Server Implementation

// src/mastra/mcp/server.ts
import { MCPServer } from "@mastra/mcp";
import { computeAccountHealthTool, runSqlTool } from "../tools";

const server = new MCPServer({
  name: "customer-analytics",
  version: "0.5.0",
  description: "Customer analytics MCP server with multi-system workflows",
  tools: {
    compute_account_health: computeAccountHealthTool,
    run_sql: runSqlTool,
  },
  resources: resourceHandlers,
});

Key Features:

• ✅ Multi-system workflows: compute_account_health combines database, external APIs, and business logic
• ✅ Resource-based discovery: Schema exploration via schema://main resource
• ✅ Transparent authentication: MCP-compliant auth context passed to tools
• ✅ Role-based access: admin/user/readonly permissions enforced per tool call
• ✅ Guardrails built-in: SELECT-only, auto-LIMIT, permission checking
• ✅ Error teaching: Structured, helpful error messages

Mastra Integration

// src/workshop-demo.ts
import { MCPClient } from "@mastra/mcp";
import { Agent } from "@mastra/core/agent";

const mcpClient = new MCPClient({
  servers: {
    customerAnalytics: {
      command: "pnpm",
      args: ["mcp-server"],
      env: { DEMO_API_KEY: "api_key_user_456" }, // Auth context
    },
  },
});

const agent = new Agent({
  name: "Customer Analytics Agent",
  model: openai("gpt-4o-mini"),
});

// Use MCP tools with agent
const response = await agent.generate(task, {
  toolsets: await mcpClient.getToolsets(),
});

HTTP Authentication (Production Pattern)

The workshop includes a production-ready HTTP server with real authentication:

// src/mastra/mcp/http-server.ts
import { MCPServer } from "@mastra/mcp";
import { server } from "./server";
import type { AuthInfo, DemoUserInfo } from "./utils";

// Authentication middleware
function authenticateRequest(req: http.IncomingMessage): AuthInfo | null {
  const authHeader = req.headers.authorization;

  // Support JWT Bearer tokens
  if (authHeader?.startsWith("Bearer ")) {
    return validateJWT(authHeader.slice(7));
  }

  // Support API keys
  if (authHeader?.startsWith("ApiKey ")) {
    return validateApiKey(authHeader.slice(7));
  }

  return null;


... [View full README on GitHub](https://github.com/mastra-ai/mcp-server-best-practice-workshop#readme)