API Server - MCP + REST API
A comprehensive API server providing Model Context Protocol (MCP) support, RESTful endpoints for file operations, command execution, project management, and AI integration.
Features
- MCP Server: Model Context Protocol compatible server for AI assistants
- REST API: RESTful endpoints for remote development control
- Real-time Communication: Server-Sent Events (SSE) for MCP
- Security: API key authentication, rate limiting, input validation
- Monitoring: Request logging and statistics dashboard
- Documentation: Interactive Swagger/OpenAPI documentation
Quick Start
1. Set Up API Key
The API key is stored in Replit Secrets as API_KEY. All authenticated endpoints require this key.
2. Access the Dashboard
Visit the root URL (/) to access the API dashboard with:
- Real-time statistics
- Request logs
- Endpoint documentation
- Security information
3. View API Documentation
Visit /docs for interactive Swagger documentation.
Authentication
All API endpoints (except /, /docs, /api/stats, /api/logs) require authentication via either:
- HTTP Header (recommended for REST API):
curl -X GET \
-H "X-API-KEY: your-api-key" \
https://your-repl.repl.co/api/project
- Query Parameter (for SSE connections):
GET /mcp?api_key=your-api-key
REST API Endpoints
File Operations
Create/Update File
POST /api/files
Content-Type: application/json
X-API-KEY: your-api-key
{
"path": "src/hello.ts",
"content": "console.log('Hello World');"
}
Read File
GET /api/files/src/hello.ts
X-API-KEY: your-api-key
Delete File
DELETE /api/files/src/hello.ts
X-API-KEY: your-api-key
Command Execution
Execute safe shell commands (whitelisted commands only):
POST /api/execute
Content-Type: application/json
X-API-KEY: your-api-key
{
"command": "ls -la",
"timeout": 10000
}
Allowed Commands: ls, cat, head, tail, wc, grep, find, echo, pwd, date, whoami, env, node, npm, npx, pnpm, yarn, git, which, mkdir, touch, cp, mv, rm
Project Structure
GET /api/project?depth=3
X-API-KEY: your-api-key
AI Prompts
POST /api/ai
Content-Type: application/json
X-API-KEY: your-api-key
{
"prompt": "Explain this code",
"context": "function add(a, b) { return a + b; }",
"maxTokens": 1000
}
MCP Server
The MCP (Model Context Protocol) server is available at /mcp and supports:
SSE Connection (GET /mcp)
Connect via Server-Sent Events for real-time MCP communication:
// Use query parameter for authentication (EventSource doesn't support custom headers)
const eventSource = new EventSource('/mcp?api_key=your-api-key');
eventSource.addEventListener('message', (event) => {
const data = JSON.parse(event.data);
console.log('Received:', data);
});
// Handle connection open
eventSource.onopen = () => {
console.log('MCP connection established');
};
// Handle errors
eventSource.onerror = (error) => {
console.error('MCP connection error:', error);
};
Note: The SSE endpoint supports api_key query parameter since EventSource API doesn't support custom headers.
JSON-RPC Tool Calls (POST /mcp)
Send MCP tool calls via HTTP:
POST /mcp
Content-Type: application/json
X-API-KEY: your-api-key
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "read_file",
"arguments": {
"path": "package.json"
}
}
}
Available MCP Tools
| Tool | Description |
|---|---|
read_file | Read file contents |
write_file | Create or update files |
list_files | List directory contents |
delete_file | Delete files or directories |
execute_command | Run safe shell commands |
get_project_structure | Get file tree |
create_directory | Create new directories |
SSH Access Setup
Replit supports SSH access for remote development with VSCode, Cursor, or any SSH client.
Step 1: Generate SSH Keys
If you don't have SSH keys, generate them:
ssh-keygen -t ed25519 -C "your_email@example.com"
Step 2: Add Public Key to Replit
- Go to Replit Account Settings
- Navigate to "SSH Keys" section
- Click "Add SSH Key"
- Paste your public key (
~/.ssh/id_ed25519.pub) - Save the key
Step 3: Get Your Repl's SSH Address
- Open your Repl
- Click on the three dots menu
- Select "Connect via SSH"
- Copy the SSH address (format:
ssh <repl-id>@ssh.replit.com)
Step 4: Configure SSH Client
Add to your ~/.ssh/config:
Host replit
HostName ssh.replit.com
User YOUR_REPL_ID
IdentityFile ~/.ssh/id_ed25519
ForwardAgent yes
ServerAliveInterval 60
ServerAliveCountMax 3
Replace YOUR_REPL_ID with your actual Repl ID.
Step 5: Connect
ssh replit
VSCode/Cursor Setup
- Install "Remote - SSH" extension
- Press
Ctrl+Shift+P→ "Remote-SSH: Connect to Host" - Select "replit" from the list
- VSCode will open a new window connected to your Repl
Security Features
Rate Limiting
- 100 requests per 15 minutes per IP
- Returns
429 Too Many Requestswhen exceeded
Input Validation
- All inputs validated with Zod schemas
- File paths sanitized to prevent directory traversal
- Commands whitelisted for safe execution
Path Traversal Protection
- Paths normalized and validated
..patterns rejected- All file operations confined to project directory
Command Sandboxing
- Only whitelisted commands allowed
- Shell operators (
|,;,&&, etc.) blocked - Timeout enforcement on all commands
Monitoring
API Statistics
GET /api/stats
Returns:
- Total requests
- Success/failure counts
- Average response time
- Server uptime
Request Logs
GET /api/logs?limit=100
Returns recent API requests with:
- Timestamp
- Method and path
- Status code
- Response time
Error Handling
All errors return JSON responses:
{
"error": "Error Type",
"message": "Detailed error message"
}
Common status codes:
400- Bad Request (invalid input)401- Unauthorized (missing API key)403- Forbidden (invalid API key)404- Not Found (resource doesn't exist)429- Too Many Requests (rate limited)500- Internal Server Error
Development
Running Locally
npm run dev
Project Structure
├── client/ # React frontend
│ └── src/
│ ├── pages/ # Page components
│ └── components/
├── server/ # Express backend
│ ├── middleware/ # Auth, logging, security
│ ├── services/ # File, command, MCP services
│ ├── routes.ts # API routes
│ └── swagger.ts # OpenAPI spec
├── shared/ # Shared types/schemas
│ └── schema.ts
└── README.md
License
MIT License