@cincoai/mcp-server

A Model Context Protocol (MCP) server implementation exposed via HTTP or STDIO for easy integration with AI agents and external applications.

Features

• ✅ HTTP Transport: Streamable HTTP transport with SSE support
• ✅ STDIO Transport: Standard I/O transport for MCP clients
• ✅ Security: CORS protection, Helmet security headers
• ✅ Stateless Mode: No session management required for simpler agent integration
• ✅ JSON Responses: Direct JSON responses for easier consumption
• ✅ Health Monitoring: Health check endpoint for monitoring
• ✅ Agent Ready: Easy integration with LangChain, custom agents, and other frameworks

Installation

Install from npm

npm install @cincoai/mcp-server

Install from source

git clone <repository-url>
cd ember-mcp
npm install
npm run build

Quick Start

1. Install the package:

npm install @cincoai/mcp-server

2. Set up environment variables - Create a .env file:

# MCP Server Configuration
MCP_TRANSPORT=http                    # Required: 'http' or 'stdio'
MCP_HTTP_PORT=3000                    # Required for HTTP transport
MCP_HTTP_HOST=0.0.0.0                 # Required for HTTP transport
MCP_CORS_ORIGINS=http://localhost:3001,http://localhost:5173  # Optional

# Security (Optional)
X_API_KEY=your-secret-key            # Optional: API key protection
WITHOUT_API_KEY=false                 # Optional: Set to 'true' to disable API key

# MongoDB Configuration
MONGODB_URI=mongodb://localhost:27017
DATABASE_NAME=ember

# API Configuration
API_URL=http://localhost:4000/graphql

3. Use in your code:

import { EmberMCPServer } from '@cincoai/mcp-server';

const server = new EmberMCPServer();
server.start().catch(console.error);

API Endpoints

MCP Endpoint

• POST /mcp - Main MCP endpoint for JSON-RPC communication

Utility Endpoints

• GET /health - Health check endpoint

Usage as a Package

Basic Usage

import { EmberMCPServer } from '@cincoai/mcp-server';

// Create and start the server
const server = new EmberMCPServer();
server.start().catch(console.error);

With Environment Variables

import { EmberMCPServer } from '@cincoai/mcp-server';
import * as dotenv from 'dotenv';

// Load environment variables
dotenv.config();

const server = new EmberMCPServer();
server
  .start()
  .then(() => console.log('✅ Server started'))
  .catch(error => {
    console.error('❌ Failed to start:', error);
    process.exit(1);
  });

TypeScript Example

import { EmberMCPServer } from '@cincoai/mcp-server';
import * as dotenv from 'dotenv';

dotenv.config();

async function main() {
  const server = new EmberMCPServer();

  try {
    await server.start();
    console.log('MCP Server is running');

    // Handle graceful shutdown
    process.on('SIGINT', () => {
      console.log('Shutting down...');
      process.exit(0);
    });
  } catch (error) {
    console.error('Error:', error);
    process.exit(1);
  }
}

main();

Standalone Script

Create server.js:

#!/usr/bin/env node
import { EmberMCPServer } from '@cincoai/mcp-server';
import * as dotenv from 'dotenv';

dotenv.config();

const server = new EmberMCPServer();
server.start().catch(console.error);

Run with:

node server.js

Pro Tips 💡

Tip 1: Environment Variables

Always configure your environment variables before starting the server:

# Required
MCP_TRANSPORT=http                    # or 'stdio'
MCP_HTTP_PORT=3000
MCP_HTTP_HOST=0.0.0.0

# Optional but recommended
X_API_KEY=your-secret-key            # For API key protection
MCP_CORS_ORIGINS=http://localhost:3001  # Comma-separated origins

Tip 2: Use dotenv for Configuration

The package automatically loads .env files, but you can also set environment variables directly:

MCP_TRANSPORT=http MCP_HTTP_PORT=3000 node server.js

Tip 3: Choose the Right Transport

• HTTP: For web applications, REST APIs, or when you need HTTP endpoints
• STDIO: For MCP clients that communicate via standard input/output

Tip 4: Error Handling

Always wrap server startup in try-catch:

try {
  await server.start();
} catch (error) {
  console.error('Startup failed:', error.message);
  // Check your environment variables and configuration
}

Tip 5: Health Check

When using HTTP transport, you can check server health:

curl http://localhost:3000/health

Tip 6: Development vs Production

# Development
npm run start:dev    # Uses tsx watch for auto-reload

# Production
npm run build        # Compile TypeScript
npm run start:prod   # Run compiled JavaScript

Usage Examples

List Available Tools

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

Call a Tool

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "get-entity",
      "arguments": {
        "entityId": "your-entity-id",
        "entityType": "project"
      }
    }
  }'

With API Key Protection

If X_API_KEY is set, include it in headers:

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

Environment Variables Reference

Required Variables

| Variable | Description | Example | | --------------- | --------------------------------------- | ----------------- | | MCP_TRANSPORT | Transport type | http or stdio | | MCP_HTTP_PORT | HTTP port (required for HTTP transport) | 3000 | | MCP_HTTP_HOST | HTTP host (required for HTTP transport) | 0.0.0.0 |

Optional Variables

| Variable | Description | Default | | ------------------ | ---------------------------- | ------- | | MCP_CORS_ORIGINS | Comma-separated CORS origins | [] | | X_API_KEY | API key for authentication | - | | WITHOUT_API_KEY | Disable API key requirement | false | | MONGODB_URI | MongoDB connection string | - | | DATABASE_NAME | Database name | - | | API_URL | GraphQL API endpoint | - |

Troubleshooting

Server won't start

1. Check environment variables: Ensure all required variables are set
2. Check port availability: Make sure the port isn't already in use
3. Verify transport type: Must be either http or stdio

"Only HTTP or STDIO transport is supported" error

Make sure MCP_TRANSPORT is set to either http or stdio:

export MCP_TRANSPORT=http  # or stdio

CORS errors

Add your frontend origin to MCP_CORS_ORIGINS:

MCP_CORS_ORIGINS=http://localhost:3001,https://yourdomain.com

API Key authentication failing

• Check that X_API_KEY environment variable matches the header value
• Or set WITHOUT_API_KEY=true to disable authentication

License

MIT