[AI Assistant] → POST /mcp → [MCP Server] → [Tool Execution] → [Response]

mcp-server/
├── src/
│   ├── tools/                  # Tool definitions
│   │   ├── sum.tool.ts         # Sum tool implementation
│   │   ├── getUser.tool.ts     # GetUser tool implementation
│   │   └── index.ts            # Tool registry
│   ├── types/                  # TypeScript type definitions
│   │   └── tool.types.ts       # Core MCP types
│   ├── middleware/             # Express middleware
│   │   ├── errorHandler.ts    # Global error handler
│   │   └── logger.ts           # Winston logger configuration
│   ├── utils/                  # Utility functions
│   │   └── validator.ts        # Input validation helper
│   ├── server.ts               # Express app configuration
│   └── index.ts                # Server entry point
├── logs/                       # Log files (auto-generated)
├── package.json
├── tsconfig.json
├── .env.example
└── README.md

npm install

PORT=3000
NODE_ENV=development
LOG_LEVEL=info

npm run build

npm run dev

npm start

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "sum",
    "input": {
      "a": 10,
      "b": 25
    }
  }'

{
  "success": true,
  "data": {
    "result": 35,
    "operation": "10 + 25 = 35"
  },
  "timestamp": "2026-04-24T10:30:00.000Z"
}

GET /health

{
  "status": "healthy",
  "timestamp": "2026-04-24T10:30:00.000Z",
  "uptime": 123.45
}

GET /tools

{
  "success": true,
  "data": {
    "count": 2,
    "tools": [
      {
        "name": "sum",
        "description": "Adds two numbers together and returns the result"
      },
      {
        "name": "getUser",
        "description": "Retrieves a user by their ID from the database"
      }
    ]
  },
  "timestamp": "2026-04-24T10:30:00.000Z"
}

POST /mcp
Content-Type: application/json

{
  "tool": "toolName",
  "input": {
    // Tool-specific input
  }
}

{
  "success": true,
  "data": {
    // Tool-specific output
  },
  "timestamp": "2026-04-24T10:30:00.000Z"
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Input validation failed",
    "details": {
      "errors": [
        {
          "path": "a",
          "message": "Expected number, received string",
          "code": "invalid_type"
        }
      ]
    }
  },
  "timestamp": "2026-04-24T10:30:00.000Z"
}

{
  "tool": "sum",
  "input": {
    "a": 15,
    "b": 30
  }
}

{
  "success": true,
  "data": {
    "result": 45,
    "operation": "15 + 30 = 45"
  },
  "timestamp": "2026-04-24T10:30:00.000Z"
}

{
  "tool": "getUser",
  "input": {
    "id": 1
  }
}

{
  "success": true,
  "data": {
    "id": 1,
    "name": "Alice Johnson",
    "email": "alice@example.com",
    "role": "admin",
    "createdAt": "2024-01-15T10:30:00Z"
  },
  "timestamp": "2026-04-24T10:30:00.000Z"
}

{
  "success": true,
  "data": null,
  "timestamp": "2026-04-24T10:30:00.000Z"
}

import { z } from "zod";
import { MCPTool } from "../types/tool.types";

// Define input schema
const myToolInputSchema = z.object({
  name: z.string().min(1),
  age: z.number().positive(),
});

type MyToolInput = z.infer<typeof myToolInputSchema>;

interface MyToolOutput {
  message: string;
}

// Implement the tool
export const myTool: MCPTool<MyToolInput, MyToolOutput> = {
  name: "myTool",
  description: "Description of what my tool does",
  inputSchema: myToolInputSchema,

  execute: async (input: MyToolInput): Promise<MyToolOutput> => {
    // Your tool logic here
    return {
      message: `Hello ${input.name}, you are ${input.age} years old!`,
    };
  },
};

import { myTool } from './myTool.tool';

constructor() {
  this.registerTool(sumTool);
  this.registerTool(getUserTool);
  this.registerTool(myTool);  // ← Add your tool here
}

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "myTool",
    "input": {
      "name": "John",
      "age": 25
    }
  }'

User: "What's the status of order #12345?"
  ↓
AI Assistant: [Calls MCP server with "getOrderStatus" tool]
  ↓
MCP Server: [Validates input, queries database]
  ↓
AI Assistant: [Receives order data]
  ↓
Response: "Your order #12345 is currently being shipped and will arrive tomorrow."

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Input validation failed",
    "details": {
      "errors": [
        {
          "path": "id",
          "message": "Number must be greater than 0",
          "code": "too_small"
        }
      ]
    }
  },
  "timestamp": "2026-04-24T10:30:00.000Z"
}