Overview

YepCode MCP Server is a Node.js implementation of a Model Context Protocol (MCP) execution server designed to run untrusted or third‑party code safely and at scale. It provides an isolated sandbox for running short‑lived scripts or plugins with controlled access to dependencies, secrets, logs, and backend services (databases, HTTP APIs). The runtime enforces limits, captures output, and exposes a simple HTTP API so orchestrators or AI agents can request code execution and receive results.

This server is useful when you need to execute custom logic or extensions that you don’t want running directly in your main app process — for example, user‑submitted transformers, assistant tools, or dynamic data processors. By centralizing execution inside a managed sandbox, you can apply consistent security policies (resource caps, network rules), audit logs, and secret‑access controls while keeping the integration developer experience simple.

Features

Sandboxed JavaScript execution with per‑job resource limits (CPU, memory, timeouts)
Dependency resolution (install on demand from npm with isolation)
Secure secret access gating (secrets mapped to job permissions)
Built‑in logging, stdout/stderr capture, and structured execution logs
Pluggable database connectors and HTTP API access helpers
HTTP API for submitting jobs, fetching logs/results, and inspecting status
Worker queue and concurrency controls for horizontal scaling
Docker and Kubernetes friendly for production deployments

Installation / Configuration

Prerequisites: Node.js 18+ and a supported database (Postgres recommended). The project includes a Dockerfile and example Kubernetes manifests.

Clone and install:

git clone https://github.com/yepcode/mcp-server-js.git
cd mcp-server-js
npm ci

Environment variables (example .env):

PORT=3000
NODE_ENV=production
DATABASE_URL=postgres://user:pass@db:5432/mcp
JWT_SECRET=replace-with-secure-secret
LOG_LEVEL=info
MAX_CONCURRENCY=8
JOB_TIMEOUT_MS=300000
SECRETS_BACKEND=env

Start locally:

# start in development
npm run dev

# production
npm start

Docker example:

docker build -t yepcode/mcp-server .
docker run -p 3000:3000 \
  -e DATABASE_URL="postgres://user:pass@db:5432/mcp" \
  -e JWT_SECRET="replace-me" \
  yepcode/mcp-server

Configuration file (optional) — mcp.config.json:

{
  "maxConcurrency": 8,
  "jobTimeoutMs": 300000,
  "dependencyCacheDir": "/var/lib/mcp/deps",
  "allowedNetworkHosts": ["api.example.com"],
  "secrets": {
    "backend": "vault",
    "vaultUrl": "https://vault.example.com"
  }
}

Available Tools

When a job runs in the MCP sandbox, common helper tools are exposed to the sandboxed code to interact safely with external resources. Typical available tools include:

fetch — HTTP client with outbound network restrictions and timeouts
- Example: await fetch(url, { method: ‘GET’ })
db — parameterized query interface (reads/writes limited by role)
- Example: await db.query(‘SELECT * FROM users WHERE id = $1’, [id])
secrets — accessor that returns permitted secrets only
- Example: const apiKey = await secrets.get(‘SERVICE_API_KEY’)
storage — object store helpers for reading/writing blobs
logger — structured log writes forwarded to server logs
- Example: logger.info(‘processing’, { jobId })

These tools are sandboxed and subject to ACLs defined by job metadata or the server configuration. The exact API surfaces can be extended via plugins.

Use Cases

AI Tooling and Assistants: Execute short helper scripts that call external APIs, transform model outputs, or fetch additional context, with strict secret and network controls.
- Example: an assistant requests a small piece of code to fetch current exchange rates, transform results, and return a normalized object.
User‑Provided Extensions: Allow customers to upload small integrations or data processors that run isolated from the main application.
- Example: users add CSV importers that parse and normalize files, then safely insert rows into a tenant‑scoped database.
Data Processing Jobs: Run ad‑hoc or scheduled transformations that require dependency installation (e.g., image processing libraries) without bloating the core service.
- Example: submit a job that installs an image resizing package, processes an input blob, and writes output to storage.
CI / Testing Harnesses: Execute test snippets or validation scripts in an isolated environment with reproducible dependency installs.

Example: Submit a Job (HTTP)

A typical execution flow exposes an HTTP endpoint that accepts a job payload, including source, dependencies, and secret references. Example request:

curl -X POST http://localhost:3000/v1/execute \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "module.exports = async ({ fetch, secrets, logger }) => { const key = await secrets.get(\"API_KEY\"); logger.info(\"got key\"); return { ok: true }; }",
    "dependencies": { "lodash": "4.17.21" },
    "secrets": ["API_KEY"],
    "timeoutMs": 60000
  }'

Response contains a job id that you can poll for status, logs, and result:

{ "jobId": "job_abc123", "status": "queued" }

Security and Scaling Notes

Always run MCP servers behind a secure network and authenticate clients (JWT or mTLS).
Use a secrets backend (HashiCorp Vault, cloud KMS) and avoid embedding secrets in environment variables.
Enforce strict network allowlists for outbound HTTP from sandboxes.
Scale horizontally by running multiple workers behind a job queue (Redis, RabbitMQ) and use health checks and metrics for orchestration.

For code-level examples and the full API reference, consult the repository README and the source code. The MCP server is intended to be extended — adapt dependency caching, secrets backends, and database connectors to your environment.

YepCode MCP Server: Secure Scalable Code Execution