apikey-mcp-server

A fully-featured Model Context Protocol (MCP) server with API-key authentication, demonstrating realistic e-commerce tools, resources, and prompts. Built on the official @modelcontextprotocol/sdk.

Quick Start

npm install
npm run build

# Start with a custom key:
API_KEY=my-secret-key npm start

# Or start without setting API_KEY — uses default key "mcp-api-key-default":
npm start

Authentication

This server requires an API key passed via the x-api-key custom header for HTTP transport access. This is the industry-standard header used by Stripe, SendGrid, GitHub REST API, and many others.

• If API_KEY env var is set: use that value as the key.
• If API_KEY env var is unset: a default key mcp-api-key-default is used, so the server is never wide open.
• stdio transport: No authentication required — stdio is launched as a local subprocess on a trusted machine.

The /health endpoint is not authenticated so load balancers and monitoring tools can probe it.

Transports

Streamable HTTP

# Start the server
API_KEY=my-secret-key npm start

# Health check (no auth required)
curl http://localhost:3000/health

# Initialize an MCP session
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "x-api-key: my-secret-key" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2026-07-28","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}'

stdio

npm run start:stdio
# Or: npx @modelcontextprotocol/inspector node dist/stdio.js

MCP Inspector

• Transport: Streamable HTTP
• URL: http://localhost:3000/mcp
• Custom Header: x-api-key = your-key-here

Configuration

Variable	Default	Description
API_KEY	mcp-api-key-default	API key for HTTP auth. Always falls back to this default if unset.
PORT	3000	HTTP server port
HOST	127.0.0.1	Bind address (auto-switches to 0.0.0.0 when K_SERVICE set — Cloud Run)
NODE_ENV	development	Environment name
MCP_LOG_BODY_LIMIT	4000	Max chars of request/response body to log

MCP Capabilities

Tools (7)

Tool	Description
search_customers	Search 25 customer records by name, email, or ID
get_order	Fetch full order details with line items, pricing, and tracking
list_products	Browse 30 products across 5 categories with text search and category filters
calculate_shipping	Estimate shipping cost by product weight and destination zone
generate_report	Generate business reports: sales, customers, orders, inventory, or summary
validate_address	Validate and standardize postal addresses with confidence scoring
ping	Connectivity and health check with uptime info

Resources (5)

URI	Description
config://app	Server configuration and feature flags (JSON)
catalog://products	Full product catalog — 30 products (JSON)
docs://api	API documentation listing all capabilities (Markdown)
customers://{id}	Individual customer record with order history (JSON)
orders://{id}	Individual order record with line items and tracking (JSON)

Prompts (4)

Prompt	Description
summarize_customer	Generate a customer summary for support staff
draft_order_email	Draft an order status email to a customer
product_recommendation	Generate personalized product recommendations
data_insights	Analyze business metrics and surface actionable insights

Mock Data

All data is in-memory (no external database required):

• 25 customers across 4 tiers (bronze / silver / gold / platinum)
• 30 products across 5 categories (Electronics, Apparel, Home, Books, Sports)
• 30 orders across 5 statuses (pending, confirmed, shipped, delivered, cancelled)
• 4 shipping zones with weight-tiered rate tables

MCP Protocol Compatibility

Spec	Transport	Status
2026-07-28	Streamable HTTP	✅ Primary
2025-11-25	HTTP + SSE	✅ Compatible

Claude Desktop Configuration

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "apikey-mcp-server": {
      "command": "node",
      "args": ["C:\\Users\\...\\apikey-mcp-server\\dist\\stdio.js"]
    }
  }
}

Docker

docker build -t apikey-mcp-server .
docker run -p 8080:8080 -e API_KEY=my-secret-key apikey-mcp-server

Scripts

Script	Description
npm run build	Compile TypeScript to dist/
npm start	Start HTTP server
npm run start:stdio	Start stdio server
npm run dev	Watch mode (TypeScript compilation only)
npm run dev:http	Hot-reload HTTP server with tsx
npm run dev:stdio	Hot-reload stdio server with tsx
npm run inspect	Launch MCP Inspector (stdio)
npm run test:smoke	Build + run smoke test
npm run clean	Remove dist/

Project Structure

src/
├── server.ts          # MCP server factory (createServer)
├── http.ts            # Streamable HTTP transport + auth middleware
├── stdio.ts           # Stdio transport entry point
├── auth.ts            # API key validation (x-api-key header)
├── config.ts          # Typed configuration loader (env vars)
├── data.ts            # Mock data store (customers, products, orders, shipping)
├── tools.ts           # 7 e-commerce tools
├── resources.ts       # 5 resources (static + templated)
├── prompts.ts         # 4 prompts
├── banner.ts          # ANSI startup banner
└── logging.ts         # Structured JSON logging with redaction
scripts/
└── smoke.mjs          # stdio smoke test

License

MIT