mqasim7/mcp-server

MCP Secure Server

A secure Model Context Protocol (MCP) server implementation with HMAC-signed token authentication, rate limiting, and comprehensive audit logging.

Features

🔒 Security

• HMAC-signed API tokens with expiration and scope-based access control
• Rate limiting (configurable, default: 60 requests/minute)
• Timestamp validation to prevent replay attacks (5-minute window)
• Comprehensive audit logging for all operations
• Secrets management via environment variables

🛠️ Tools

• ping - Returns server status and timestamp
• search_records - Query a local dataset with filtering options
• create_integration - Persist integration configurations locally

📊 Monitoring & Observability

• Structured logging with Winston
• Audit trail for security events
• Rate limiting headers
• Health check endpoint

Quick Start

1. Installation

git clone <repository-url>
cd mcp-secure-server
npm install

2. Environment Setup

cp .env.example .env
# Edit .env with your configuration

Important: Change the default secrets in production!

3. Initialize Data Directories

npm run setup

4. Development

# Start in development mode
npm run dev

# Or build and start
npm run build
npm start

The server will start on http://localhost:3000 (configurable via PORT environment variable).

Environment Variables

API Documentation

Authentication

All MCP endpoints require a Bearer token in the Authorization header:

Authorization: Bearer <your-token>

Generate Token

Generate a new API token:

POST /auth/token
Content-Type: application/json

{
  "userId": "your-user-id",
  "scope": "read" // or "write"
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "userId": "your-user-id",
  "scope": "read",
  "expiresIn": 3600
}

Health Check

Check server status (no authentication required):

GET /health

Response:

{
  "status": "ok",
  "timestamp": "2024-03-07T10:30:00.000Z",
  "version": "1.0.0"
}

List Tools

Get available tools:

POST /mcp/tools/list
Content-Type: application/json
Authorization: Bearer <token>

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "ping",
        "description": "Returns server status and current timestamp",
        "inputSchema": {
          "type": "object",
          "properties": {},
          "required": []
        }
      },
      // ... other tools
    ]
  }
}

Tool Execution

Execute a tool:

POST /mcp/tools/call
Content-Type: application/json
Authorization: Bearer <token>

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "<tool-name>",
  "params": { /* tool-specific parameters */ }
}

Tools Reference

1. ping

Returns server status and timestamp.

Scope Required: Any (read/write)

Parameters: None

Example:

curl -X POST http://localhost:3000/mcp/tools/call \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "ping",
    "params": {}
  }'

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "status": "ok",
    "timestamp": "2024-03-07T10:30:00.000Z",
    "serverTime": 1709810200000,
    "uptime": 3600.5,
    "version": "1.0.0"
  }
}

2. search_records

Search through local dataset records.

Scope Required: read or write

Parameters:

• query (optional): Text search query
• category (optional): Filter by category
• tags (optional): Array of tags to filter by (AND operation)
• limit (optional): Maximum results (1-100, default: 10)

Example:

curl -X POST http://localhost:3000/mcp/tools/call \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "search_records",
    "params": {
      "query": "API",
      "category": "Security",
      "tags": ["auth", "jwt"],
      "limit": 5
    }
  }'

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "records": [
      {
        "id": "rec_002",
        "name": "User Authentication Service",
        "description": "OAuth2 and JWT-based authentication service",
        "category": "Security",
        "tags": ["auth", "oauth2", "jwt", "security"],
        "data": { /* ... */ },
        "createdAt": "2024-01-10T09:15:00.000Z",
        "updatedAt": "2024-02-10T16:45:00.000Z"
      }
    ],
    "total": 1,
    "query": "API",
    "filters": {
      "category": "Security",
      "tags": ["auth", "jwt"]
    }
  }
}

3. create_integration

Create and persist a new integration configuration.

Scope Required: write

Parameters:

• name (required): Integration name (1-100 chars)
• type (required): One of: webhook, api, database, file, custom
• config (required): Configuration object (type-specific validation)

Type-specific config requirements:

• webhook: config.url (string)
• api: config.endpoint (string)
• database: config.connectionString (string)
• file: config.path (string)
• custom: any object

Example:

curl -X POST http://localhost:3000/mcp/tools/call \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <write-token>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "create_integration",
    "params": {
      "name": "Payment Webhook",
      "type": "webhook",
      "config": {
        "url": "https://api.example.com/webhooks/payments",
        "method": "POST",
        "headers": {
          "Authorization": "Bearer secret",
          "Content-Type": "application/json"
        },
        "retries": 3
      }
    }
  }'

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "integration": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Payment Webhook",
      "type": "webhook",
      "config": {
        "url": "https://api.example.com/webhooks/payments",
        "method": "POST",
        "headers": { /* ... */ },
        "retries": 3
      },
      "createdAt": "2024-03-07T10:30:00.000Z",
      "updatedAt": "2024-03-07T10:30:00.000Z",
      "userId": "your-user-id"
    },
    "message": "Integration created successfully"
  }
}

Security Features

HMAC Token Authentication

Tokens are JWT-signed with an additional HMAC signature for enhanced security:

1. JWT Layer: Standard JWT with RSA/HMAC signing
2. HMAC Layer: Additional HMAC-SHA256 signature of the payload
3. Double Verification: Both signatures must be valid

Scope-based Access Control

• read: Can access ping and search_records
• write: Can access all tools including create_integration

Replay Attack Protection

• Tokens include creation timestamp
• Requests are rejected if token is older than MAX_TOKEN_AGE_MINUTES (default: 5 minutes)
• Use fresh tokens for each session

Rate Limiting

• Per-token rate limiting using token hash
• Configurable limits via environment variables
• Rate limit headers included in responses:
  • X-RateLimit-Limit
  • X-RateLimit-Remaining
  • X-RateLimit-Reset

Audit Logging

All operations are logged with:

• Timestamp
• User ID
• Tool/method called
• Success/failure status
• Response latency
• Error details (if any)
• Client IP (if available)

Audit logs are stored separately from application logs for security compliance.

Testing

Automated Test Suite

Run the comprehensive test suite:

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

Postman Collection

A complete Postman collection is available for API testing:

📁 postman/ directory contains:

• MCP-Secure-Server.postman_collection.json - 25+ API requests
• MCP-Server-Environment.postman_environment.json - Environment setup
• README.md - Detailed usage instructions

Quick Setup:

1. Import both files into Postman
2. Start the server: npm start
3. Run the collection for automated testing

Features:

• ✅ 60+ automated test assertions
• ✅ Complete security testing scenarios
• ✅ Authentication & authorization tests
• ✅ Rate limiting validation
• ✅ Error handling verification
• ✅ JSON-RPC 2.0 compliance checks

Test Coverage

The test suite covers:

• ✅ Token generation and validation
• ✅ HMAC signature verification
• ✅ Expired token rejection
• ✅ Replay attack protection
• ✅ Scope validation
• ✅ Rate limiting
• ✅ All tool functionality
• ✅ Error handling
• ✅ Integration tests

Sample Requests

Complete Workflow Example

# 1. Generate a read token
READ_TOKEN=$(curl -s -X POST http://localhost:3000/auth/token \
  -H "Content-Type: application/json" \
  -d '{"userId": "demo-user", "scope": "read"}' | \
  jq -r '.token')

# 2. Generate a write token
WRITE_TOKEN=$(curl -s -X POST http://localhost:3000/auth/token \
  -H "Content-Type: application/json" \
  -d '{"userId": "demo-user", "scope": "write"}' | \
  jq -r '.token')

# 3. List available tools
curl -X POST http://localhost:3000/mcp/tools/list \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $READ_TOKEN" \
  -d '{"jsonrpc": "2.0", "id": 1}'

# 4. Ping the server
curl -X POST http://localhost:3000/mcp/tools/call \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $READ_TOKEN" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "ping", "params": {}}'

# 5. Search for API-related records
curl -X POST http://localhost:3000/mcp/tools/call \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $READ_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "search_records",
    "params": {"query": "API", "limit": 3}
  }'

# 6. Create an integration (requires write token)
curl -X POST http://localhost:3000/mcp/tools/call \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $WRITE_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "create_integration",
    "params": {
      "name": "Demo API Integration",
      "type": "api",
      "config": {
        "endpoint": "https://jsonplaceholder.typicode.com/posts",
        "method": "GET",
        "timeout": 5000
      }
    }
  }'

Development

Project Structure

mcp-secure-server/
├── src/
│   ├── auth/           # Authentication logic
│   ├── middleware/     # Express middleware
│   ├── tools/          # MCP tools implementation
│   ├── types/          # TypeScript type definitions
│   ├── utils/          # Utilities (config, logging)
│   ├── __tests__/      # Test files
│   └── index.ts        # Main server file
├── data/               # JSON data files
├── logs/               # Log files
├── .env.example        # Environment variables template
└── package.json

Adding New Tools

1. Create tool implementation in src/tools/
2. Export tool schema and handler
3. Register in src/index.ts
4. Add tests in src/__tests__/

Scripts

• npm run dev - Start development server with hot reload
• npm run build - Build TypeScript to JavaScript
• npm start - Start production server
• npm test - Run test suite
• npm run lint - Type check with TypeScript
• npm run setup - Initialize data directories and environment

Security Best Practices

1. Change default secrets in production environments
2. Use HTTPS in production
3. Set strong environment variables for JWT and HMAC secrets
4. Monitor audit logs regularly
5. Implement additional rate limiting at reverse proxy level
6. Regularly rotate secrets
7. Use scoped tokens - generate read tokens for read-only operations

Production Deployment

1. Set NODE_ENV=production
2. Configure strong secrets in environment variables
3. Set up proper log rotation
4. Configure reverse proxy (nginx/Apache) with HTTPS
5. Set up monitoring and alerting
6. Implement backup strategies for data files

License

MIT

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

Support

For issues and questions, please use the GitHub issue tracker.