MCP Server Template for OpenAI-Compatible Backends

A production-ready Model Context Protocol (MCP) server template that connects to any OpenAI-compatible API backend. Build AI agent tools in minutes, not hours.

Why This Template?

The Model Context Protocol is the 2026 standard for connecting AI models to external tools and data sources. This template gives you a battle-tested starting point for building MCP servers that work with any OpenAI-compatible API — including XiDao, OpenRouter, Together AI, LiteLLM, and self-hosted vLLM/Ollama instances.

Features

• 🔌 OpenAI-Compatible — Works with any provider via base_url switching
• 🛠️ Pre-built Tools — File operations, web search, code execution, database queries
• 🔒 Authentication — API key, OAuth, and custom auth middleware
• 📊 Observability — Built-in OpenTelemetry tracing and structured logging
• 🧪 Test Suite — Comprehensive tests with mock backends
• 🐳 Docker Ready — One-command deployment with Docker Compose
• 📝 Type Safety — Full TypeScript type definitions for all tool schemas
• 🔄 Hot Reload — Development mode with automatic restart on file changes

Quick Start

1. Clone and Install

git clone https://github.com/XidaoApi/mcp-server-template.git
cd mcp-server-template
npm install

2. Configure

cp .env.example .env
# Edit .env with your API settings:
# OPENAI_API_KEY=***
# OPENAI_BASE_URL=https://api.xidao.online/v1  # or any OpenAI-compatible endpoint
# OPENAI_MODEL=gpt-5

3. Run

# Development (with hot reload)
npm run dev

# Production
npm run build && npm start

# Docker
docker compose up -d

Architecture

mcp-server-template/
├── src/
│   ├── server.ts          # MCP server entry point
│   ├── tools/             # Tool implementations
│   │   ├── file-ops.ts    # File read/write/search
│   │   ├── web-search.ts  # Web search via multiple providers
│   │   ├── code-exec.ts   # Sandboxed code execution
│   │   └── db-query.ts    # Database query tool
│   ├── auth/              # Authentication middleware
│   │   ├── api-key.ts     # API key validation
│   │   └── oauth.ts       # OAuth 2.0 flow
│   ├── llm/               # LLM integration layer
│   │   ├── client.ts      # OpenAI-compatible client
│   │   ├── router.ts      # Multi-provider routing
│   │   └── fallback.ts    # Automatic failover
│   └── telemetry/         # Observability
│       ├── tracing.ts     # OpenTelemetry spans
│       └── metrics.ts     # Prometheus metrics
├── tests/
├── docker-compose.yml
├── Dockerfile
└── package.json

Available Tools

Tool	Description	Example
read_file	Read file contents	Read config files, source code
write_file	Write to files	Generate reports, save data
search_files	Search files by pattern	Find functions, grep logs
web_search	Search the web	Research topics, verify facts
execute_code	Run code in sandbox	Test snippets, data processing
db_query	Query databases	SQL, MongoDB, Redis
http_request	Make HTTP calls	API integrations, webhooks

Custom Tools

Add your own tools in src/tools/:

// src/tools/my-tool.ts
import { Tool, ToolSchema } from '@modelcontextprotocol/sdk';

export const myTool: Tool = {
  name: 'my_custom_tool',
  description: 'Does something useful',
  inputSchema: {
    type: 'object',
    properties: {
      query: { type: 'string', description: 'Input query' },
    },
    required: ['query'],
  },
  async execute(params) {
    // Your implementation
    return { result: `Processed: ${params.query}` };
  },
};

Register it in src/server.ts:

import { myTool } from './tools/my-tool';
server.addTool(myTool);

Multi-Provider Routing

The template includes a built-in router for using multiple LLM providers:

// src/llm/router.ts
const router = new LLMRouter({
  providers: [
    { name: 'xidao', baseUrl: 'https://api.xidao.online/v1', priority: 1 },
    { name: 'openai', baseUrl: 'https://api.openai.com/v1', priority: 2 },
    { name: 'ollama', baseUrl: 'http://localhost:11434/v1', priority: 3 },
  ],
  strategy: 'cost-optimized',  // or 'latency-optimized', 'round-robin'
  fallback: true,
});

Environment Variables

Variable	Description	Default
OPENAI_API_KEY	API key for the LLM provider	Required
OPENAI_BASE_URL	OpenAI-compatible API endpoint	https://api.openai.com/v1
OPENAI_MODEL	Model to use	gpt-5
MCP_PORT	Server port	3000
MCP_LOG_LEVEL	Logging level	info
OTEL_ENDPOINT	OpenTelemetry collector URL	—
AUTH_MODE	Authentication mode	api-key

Deployment

Docker Compose (Recommended)

services:
  mcp-server:
    build: .
    ports:
      - "3000:3000"
    environment:
      - OPENAI_API_KEY=***
      - OPENAI_BASE_URL=${OPENAI_BASE_URL}
    restart: unless-stopped

Kubernetes

kubectl apply -f k8s/

See k8s/ directory for manifests.

Testing

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run specific test suite
npm test -- --grep "file-ops"

Related Projects

• MCP Specification — The official MCP docs
• MCP SDK — TypeScript SDK
• XiDao API Gateway — OpenAI-compatible API gateway with multi-provider routing, failover, and cost optimization

License

MIT — see LICENSE for details.