# 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

```bash
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

```bash
# 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

```bash
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](https://modelcontextprotocol.io/specification/2026-07-28) | Streamable HTTP | ✅ Primary |
| [2025-11-25](https://modelcontextprotocol.io/specification/2025-11-25) | HTTP + SSE | ✅ Compatible |

## Claude Desktop Configuration

Add to `claude_desktop_config.json`:

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

## Docker

```bash
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