akhshyganesh/mcp-http-proxy

🌐 MCP HTTP Proxy

A powerful Model Context Protocol (MCP) server that provides HTTP request proxying for AI applications. All responses are structured for AI consumption with consistent status, data, and error fields.

📋 Repository Information

🤖 What is MCP?

The Model Context Protocol (MCP) is an open standard that enables secure connections between AI applications and external data sources. This server implements MCP to provide AI assistants with the ability to perform HTTP operations against external APIs through a standardized interface.

✨ Features

• 🌐 HTTP Request Proxying: Support for GET, POST, PUT, DELETE methods to external APIs
• 🖥️ Curl Proxy: Uses system curl commands to communicate with target servers
• 🤖 AI-Friendly Responses: Structured JSON responses with status, HTTP code, data, and error fields
• 🛡️ Intelligent Error Handling: Provides helpful guidance for common HTTP errors (401, 403, 429, etc.)
• ✅ Schema Validation: Input validation using Zod schemas
• 🔒 Security: Built-in timeout protection and input sanitization to prevent command injection
• 📘 TypeScript: Fully typed implementation with the MCP SDK

🏗️ Architecture

graph LR
    A[AI Assistant] <--> B[MCP Client]
    B <--> C[This MCP Server]
    C <--> D[Curl]
    D <--> E[Target API Server]

The server receives MCP requests, validates input, constructs curl commands, executes them, and returns structured responses.

🚀 Installation & Setup

📦 For End Users (Recommended)

Option 1: Install from NPM (Easiest)

# Install globally to use anywhere
npm install -g mcp-http-proxy

# Start the server
mcp-http-proxy

Option 2: Install from GitHub

# Install directly from the repository
npm install -g git+https://github.com/akhshyganesh/mcp-http-proxy.git

# Start the server
mcp-http-proxy

Option 3: Use with npx (No Installation)

# Run directly without installing
npx mcp-http-proxy

🛠️ For Developers

1️⃣ Clone and Install Dependencies

git clone https://github.com/akhshyganesh/mcp-http-proxy.git
cd mcp-http-proxy
npm install

2️⃣ Build the Project

npm run build

3️⃣ Start the Server

npm start
# or for development with auto-reload
npm run dev

🔧 MCP Client Configuration

Once installed, you can use this server with any MCP-compatible client. Here are example configurations:

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-http-proxy": {
      "command": "mcp-http-proxy"
    }
  }
}

VS Code MCP Extension

Add to your .vscode/mcp.json:

{
  "mcpServers": {
    "mcp-http-proxy": {
      "command": "mcp-http-proxy"
    }
  }
}

🛠️ Development

📜 Available Scripts

📁 Project Structure

├── 📂 src/
│   ├── 📄 index.ts              # Main MCP server implementation
│   └── 📂 @types/               # Custom type declarations
│       └── 📄 modelcontextprotocol__sdk.d.ts
├── 📂 tests/                    # Test files
│   ├── 📄 server.test.ts        # Server functionality tests
│   └── 📄 setup.ts              # Test setup configuration
├── 📂 dist/                     # Compiled JavaScript (generated, not tracked)
├── 📂 .vscode/
│   ├── 📄 mcp.json             # VS Code MCP integration config
│   └── 📄 tasks.json           # VS Code build tasks
├── 📂 .github/
│   └── 📂 workflows/
│       └── 📄 ci.yml           # Continuous Integration pipeline
├── 📄 jest.config.js           # Jest testing configuration
├── 📄 .eslintrc.js             # ESLint configuration
├── 📄 .npmignore               # NPM package exclusions
│   └── 📄 copilot-instructions.md # GitHub Copilot workspace instructions
├── 📄 test-requests.json        # Sample test requests
├── 📄 test-requests.md          # Test requests documentation
├── 📄 package.json              # Project dependencies and scripts
├── 📄 tsconfig.json            # TypeScript configuration
├── 📄 tsconfig.build.json      # TypeScript build configuration
├── 📄 .gitignore               # Git ignore patterns
├── 📄 LICENSE                  # MIT license file
└── 📄 README.md               # This file

📖 Usage

📥 Input Schema

The server accepts requests with the following structure:

interface Request {
  method: 'GET' | 'POST' | 'PUT' | 'DELETE';
  url: string;                    // Valid URL
  data?: Record<string, any>;     // Request body (for POST/PUT)
  headers?: Record<string, string>; // HTTP headers
}

📤 Response Schema

All responses follow this structure:

interface Response {
  status: 'ok' | 'error';
  code: number;                   // HTTP status code
  data: any;                      // Response body (parsed JSON if possible)
  error?: string;                 // Error message (if status is 'error')
}

💡 Examples

📋 GET Request

{
  "method": "GET",
  "url": "https://api.example.com/users/123",
  "headers": {
    "Authorization": "Bearer token123"
  }
}

➕ POST Request

{
  "method": "POST",
  "url": "https://api.example.com/users",
  "headers": {
    "Content-Type": "application/json"
  },
  "data": {
    "name": "John Doe",
    "email": "john@example.com"
  }
}

✅ Success Response

{
  "status": "ok",
  "code": 200,
  "data": {
    "id": 123,
    "name": "John Doe",
    "email": "john@example.com"
  }
}

❌ Error Response

{
  "status": "error",
  "code": 401,
  "data": {
    "message": "Unauthorized"
  },
  "error": "Authentication required (HTTP 401). The API endpoint requires authentication. Please provide an Authorization header (e.g., \"Authorization\": \"Bearer YOUR_TOKEN\" or \"Authorization\": \"Basic YOUR_CREDENTIALS\"). Check the API documentation for the correct authentication method."
}

🚨 Intelligent Error Handling

The server provides helpful guidance for common HTTP errors:

Each error response includes specific, actionable guidance to help resolve the issue quickly.

💻 VS Code Integration

🔧 Setting Up MCP in VS Code

1️⃣ Install an MCP Extension

Install one of these MCP extensions in VS Code:

📦 automatalabs.copilot-mcp
📦 buildwithlayer.mcp-integration-expert-eligr  
📦 semanticworkbenchteam.mcp-server-vscode

2️⃣ Configure MCP Settings

The .vscode/mcp.json file is already configured:

{
  "servers": {
    "curl": {
      "type": "stdio",
      "command": "node",
      "args": ["dist/index.js"]
    }
  }
}

3️⃣ Build and Start

npm run build
npm start

4️⃣ Use in VS Code

Open VS Code's command palette (Cmd+Shift+P) and look for MCP-related commands to interact with your server.

🧪 Testing with Dummy Endpoints

Here are some free JSON API endpoints you can use for testing:

🏷️ JSONPlaceholder (Fake REST API)

• 🌐 Base URL: https://jsonplaceholder.typicode.com
• 📋 Features: Users, Posts, Comments, Albums, Photos, Todos

🔬 Example Requests to Test Your MCP Server

{
  "method": "GET",
  "url": "https://jsonplaceholder.typicode.com/users"
}

{
  "method": "GET",
  "url": "https://jsonplaceholder.typicode.com/users/1"
}

{
  "method": "POST",
  "url": "https://jsonplaceholder.typicode.com/posts",
  "headers": {
    "Content-Type": "application/json"
  },
  "data": {
    "title": "My New Post",
    "body": "This is the content of my post",
    "userId": 1
  }
}

{
  "method": "PUT",
  "url": "https://jsonplaceholder.typicode.com/posts/1",
  "headers": {
    "Content-Type": "application/json"
  },
  "data": {
    "id": 1,
    "title": "Updated Post Title",
    "body": "Updated post content",
    "userId": 1
  }
}

{
  "method": "DELETE",
  "url": "https://jsonplaceholder.typicode.com/posts/1"
}

🌐 Other Test APIs

🔄 VS Code Usage Workflow

graph TD
    A[🚀 Start MCP Server] --> B[📖 Open VS Code]
    B --> C[⌨️ Access MCP Commands]
    C --> D[📨 Send HTTP Requests]
    D --> E[👀 View JSON Responses]
    
    A1[npm start] --> A
    C1[Cmd+Shift+P → MCP] --> C

1. 🚀 Start the MCP Server: Run npm start in your terminal
2. 📖 Open VS Code: Open any file or workspace
3. ⌨️ Access MCP Commands: Use Cmd+Shift+P → Search for "MCP"
4. 📨 Send Requests: Use the MCP interface to send HTTP requests through your server
5. 👀 View Responses: See structured JSON responses in VS Code

🧪 Testing Commands

The repository includes a comprehensive test-requests.json file with sample requests for testing all HTTP operations. For detailed information about each test request, see .

📋 Test Coverage Includes:

• JSONPlaceholder API: Users and Posts HTTP operations
• HTTPBin API: HTTP testing with custom headers
• ReqRes API: User API with pagination

You can use these test requests directly with your MCP client to verify the server functionality.

🔒 Security Considerations

🔧 Troubleshooting

⚠️ Common Issues

💡 Development Tips

• 👀 Use npm run dev for watch mode during development
• 🔍 Check VS Code problems panel for TypeScript errors
• 🚀 Test with simple GET requests first
• ✅ Validate JSON responses from target servers

🤝 Contributing

We welcome contributions to improve the MCP HTTP Proxy server! Here's how you can contribute:

🚀 Quick Start

1. 🍴 Fork the repository on GitHub: akhshyganesh/mcp-http-proxy
2. 🌿 Create a feature branch: git checkout -b feature/your-feature-name
3. ✨ Make your changes and ensure they follow the existing code style
4. 🧪 Add tests if applicable
5. 💾 Commit your changes: git commit -am 'Add some feature'
6. 📤 Push to the branch: git push origin feature/your-feature-name
7. 🔄 Submit a pull request through GitHub

📋 Development Guidelines

• ✅ Follow TypeScript best practices
• 📝 Use meaningful commit messages
• 📚 Update documentation for new features
• 🏗️ Ensure all builds pass before submitting PR

📚 References

• 📖 Model Context Protocol Documentation
• 🛠️ MCP SDK Reference
• 📘 TypeScript Documentation
• ✅ Zod Schema Validation

🧪 Testing

Running Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

Test Coverage

The test suite includes:

• ✅ Server startup tests - Ensures the server starts without crashing
• ✅ Executable validation - Verifies CLI binary has correct shebang
• ✅ Module import tests - Confirms the module can be imported
• ✅ Build verification - Validates TypeScript compilation

Continuous Integration

GitHub Actions automatically:

• ✅ Runs tests on multiple Node.js versions (18, 20, 22)
• ✅ Tests on multiple platforms (Ubuntu, Windows, macOS)
• ✅ Performs security audits
• ✅ Validates code quality with ESLint

🔒 Security

Security Features

• ✅ Input Sanitization - All user inputs are validated and sanitized
• ✅ Command Injection Protection - Safe curl command construction
• ✅ Timeout Protection - Prevents hanging requests
• ✅ Error Handling - Secure error messages without sensitive data
• ✅ Dependency Scanning - Regular security audits of dependencies

Security Auditing

# Run security audit
npm audit

# Fix security issues
npm audit fix

# Check for high-severity vulnerabilities
npm audit --audit-level=high

Reporting Security Issues

If you discover a security issue, please:

1. DO NOT open a public GitHub issue
2. Email security concerns to: akhshy.balakannan@gmail.com
3. Include details about the vulnerability
4. Allow time for the issue to be addressed before public disclosure

🤝 Contributing

Development Workflow

1. Fork the repository
2. Clone your fork locally
3. Install dependencies: npm install
4. Build the project: npm run build
5. Run tests: npm test
6. Make changes and add tests
7. Lint code: npm run lint:fix
8. Create a pull request

Code Quality Standards

• ✅ All code must pass TypeScript compilation
• ✅ All tests must pass
• ✅ Code coverage should not decrease
• ✅ ESLint rules must be followed
• ✅ Security audit must pass

📄 License

This project is licensed under the MIT License - see the file for details.