Build MCP Server with Node.js - Step by Step

Project setup

This guide walks through building a simple Node.js MCP server, then connecting it to Claude Desktop. You can start with a generated MCP server or build a thin wrapper if you already have an OpenAPI spec.

• Node.js 18 or later.
• An OpenAPI spec for your API.
• LegacyAI CLI or dashboard access.

Scaffold the server

If you are using LegacyAI generation, the scaffold includes tool schemas, routing, and a runtime that forwards requests to your API. If you are building manually, keep the server thin and focused on validation and forwarding rather than business logic.

Store generated code in a dedicated folder so you can regenerate without overwriting custom changes. Keep any customization in a separate wrapper module.

Step 1: Generate tools from OpenAPI

Use LegacyAI to generate a Node.js MCP server from your OpenAPI file. This gives you a tool catalog and validated schemas out of the box.

Step 2: Wire environment variables

Store API base URLs and tokens in environment variables so you do not hardcode secrets.

export API_BASE_URL="https://api.yourcompany.com"
export API_TOKEN="your-token"

Step 3: Start the MCP server

Run the generated server locally. It will expose a tool catalog for Claude Desktop and forward calls to your API.

node legacyai-mcp-server.js

Step 3.5: Add validation and error handling

Ensure every tool call validates required fields and fails fast when inputs are incomplete. Consistent error responses help the model recover and choose the right next action.

LegacyAI includes validation by default, but if you add custom tools, keep error messages short and structured so the agent can respond appropriately.

Step 4: Configure Claude Desktop

Add the MCP server to your Claude Desktop config so tools appear automatically.

{
  "mcpServers": [
    {
      "name": "LegacyAI Node",
      "command": "node",
      "args": ["./legacyai-mcp-server.js"],
      "env": {
        "API_BASE_URL": "https://api.yourcompany.com",
        "API_TOKEN": "${API_TOKEN}"
      }
    }
  ]
}

Step 5: Validate tool calls

Ask Claude to call a read-only endpoint first. Confirm the response, then enable write tools if needed.

Local testing checklist

• Run a tool call with missing parameters to confirm validation.
• Verify auth headers are injected correctly.
• Simulate a 500 response and ensure the error is handled.
• Inspect logs for full request and response traces.

Recommended structure

• Keep tool schemas in a generated folder so regeneration is safe.
• Add middleware for logging and request tracing.
• Use a separate token per environment.

Deployment checklist

• Run the MCP server as a separate service with health checks.
• Secure secrets with a vault or environment manager.
• Enable rate limits and request timeouts.
• Set up alerts for tool call failures.