MCP Express Adapter

🚀 MCP Middleware Server Usage Guide

MCP (Middleware Proxy) is a powerful middleware proxy server designed for handling complex request routing and backend service calls. It supports multiple protocols, including HTTP, HTTPS, and WebSocket, and offers a rich set of middleware features.

🚀 Quick Start

✨ Features

• Multi - protocol Support: Supports HTTP, HTTPS, and WebSocket.
• Rich Middleware Functions: Allows for custom middleware addition, such as logging and request rewriting.
• Flexible Routing Rules: Enables direct target specification and dynamic backend service selection based on request paths.

📦 Installation

Before using MCP, make sure you have installed Node.js (version 8.0 or higher) and npm (version 5.0 or higher). Then you can install it via the following command:

npm install mcp-express-adapter --save

💻 Usage Examples

Basic Usage

MCP proxy can route requests to multiple backend services through simple configuration. Here is a basic configuration example:

const express = require('express');
const cors = require('cors');
const { MCPClient } = require('mcp-express-adapter');

const app = express();
app.use(cors());

// Create an MCP proxy instance, specifying the processing path and backend service address
const mcpProxy = new MCPClient({
  endpoint: '/mcp', // Proxy processing path
  upstream: 'http://localhost:3001' // Backend service address
});

// Mount the proxy server to the main application
app.use('/mcp', mcpProxy.middleware());

// Apply the global JSON parsing middleware, which must be registered after the proxy middleware
app.use(express.json());

const PORT = 3000;
app.listen(PORT, () => {
  console.log(`MCP proxy server has been started, listening on port ${PORT}`);
});

Advanced Usage

MCP also supports more complex routing rules and custom middleware:

const express = require('express');
const cors = require('cors');
const { MCPClient } = require('mcp-express-adapter');

const app = express();
app.use(cors());

// Create multiple proxy instances, each handling a different request path
const agent1 = new MCPClient({
  endpoint: '/agent-1',
  upstream: 'http://localhost:3001',
});

const agent2 = new MCPClient({
  endpoint: '/agent-2',
  upstream: 'http://localhost:3002',
});

// Mount the proxy instances to different paths
app.use('/agent-1', agent1.middleware());
app.use('/agent-2', agent2.middleware());

// Apply the global JSON parsing middleware, which must be registered after all proxy middleware
app.use(express.json());

const PORT = 3000;
app.listen(PORT, () => {
  console.log(`MCP proxy server has been started, listening on port ${PORT}`);
});

Middleware Extension

Custom Logging

You can add custom middleware to the proxy instance to enhance its functionality:

// Create a proxy instance with custom logging
const agentWithLogging = new MCPClient({
  endpoint: '/logging',
  upstream: 'http://localhost:3001'
});

// Add logging middleware to record request and response information
agentWithLogging.use((req, res, next) => {
  console.log(`[Custom Log] Received request: ${req.url}`);
  next();
});

Request Rewriting

MCP allows you to deeply customize requests, including modifying request headers, paths, and parameters:

const agentRewrite = new MCPClient({
  endpoint: '/rewrite',
  upstream: 'http://localhost:3001'
});

agentRewrite.use((req, res, next) => {
  // Modify the request path
  req.url = `/new-path${req.url}`;
  
  // Add custom header information
  req.headers['x-custom-header'] = 'some-value';
  
  next();
});

Request Forwarding Rules

MCP provides flexible routing rules, which can be configured in the following ways:

// Directly specify the target address
agent1.setTarget('http://localhost:3001');

// Select different backend services based on the request path
agent2.use((req, res) => {
  if (req.url.startsWith('/api')) {
    agent2.addTarget('http://backend1:8080');
  } else {
    agent2.addTarget('http://backend2:8080');
  }
});

Common Issues

• How to handle request timeouts?
  MCP provides a powerful error handling mechanism, and you can customize the timeout strategy through middleware.
• Does it support WebSocket?
  Yes, MCP fully supports the WebSocket protocol and provides routing functionality for WebSocket requests.

Example Code

Create a Simple Proxy Server

const express = require('express');
const cors = require('cors');
const { MCPClient } = require('mcp-express-adapter');

const app = express();
app.use(cors());

// Create a basic proxy instance
const mcpProxy = new MCPClient({
  endpoint: '/api', // Processing path
  upstream: 'http://localhost:3001' // Backend service address
});

// Mount the proxy server to the main application
app.use('/api', mcpProxy.middleware());

// Apply the global JSON parsing middleware, which must be registered after the proxy middleware
app.use(express.json());

const PORT = 3000;
app.listen(PORT, () => {
  console.log(`MCP proxy server has been started, listening on port ${PORT}`);
});

Create a Server with Multiple Proxies

const express = require('express');
const cors = require('cors');
const { MCPClient } = require('mcp-express-adapter');

const app = express();
app.use(cors());

// Create multiple proxy instances, each handling a different request path
const agent1 = new MCPClient({
  endpoint: '/agent-1',
  upstream: 'http://localhost:3001'
});

const agent2 = new MCPClient({
  endpoint: '/agent-2',
  upstream: 'http://localhost:3002'
});

// Mount the proxy instances to different paths
app.use('/agent-1', agent1.middleware());
app.use('/agent-2', agent2.middleware());

// Apply the global JSON parsing middleware, which must be registered after all proxy middleware
app.use(express.json());

const PORT = 3000;
app.listen(PORT, () => {
  console.log(`MCP proxy server has been started, listening on port ${PORT}`);
});

Testing

Test with curl

# Test a basic request
curl -X GET http://localhost:3000/api/test

# Test a request with parameters
curl -X POST -H "Content-Type: application/json" -d '{"name":"test"}' http://localhost:3000/api/test

Test with Postman

1. Open Postman.
2. Add a new request and enter the proxy server address (e.g., http://localhost:3000).
3. Configure the request method and parameters as needed.

Notes

⚠️ Important Note

• Error Handling: MCP provides a powerful error handling mechanism. You can customize error - handling logic through middleware.
• Performance Optimization: To improve performance, it is recommended to enable gzip compression and use connection pools.
• Security Considerations: In a production environment, make sure to configure an SSL certificate to protect communication security.

📚 Documentation

For more detailed information, please refer to the MCP Middleware Server Documentation.