HTTP Service Proxy Configuration
The following is a specific configuration example for HTTP service proxy, including routing, tools and other configurations:Configuration Explanation
1. Basic Configuration
port
port
MCP Gateway service listening port, default 5235
pid
pid
Process ID file path for process management and reloading
reload_interval
reload_interval
Configuration reload interval, default 600s
reload_switch
reload_switch
Whether to enable automatic configuration reloading
name: Proxy service name, globally unique, used to identify different proxy servicestenant: Tenant identifier for data isolation and permission management in multi-tenant scenarios
2. Routing Configuration
Routing configuration is used to define request forwarding rules:prefix:
- SSE:
${prefix}/sse, e.g.,/gateway/user/sse - SSE:
${prefix}/message, e.g.,/gateway/user/message - StreamableHTTP:
${prefix}/mcp, e.g.,/gateway/user/mcp
3. CORS Configuration
Cross-Origin Resource Sharing (CORS) configuration is used to control access permissions for cross-origin requests:Usually, MCP Clients do not need to open cross-origin
4. Service Configuration
Service configuration is used to define service metadata, associated tool lists, and service-level configuration:{{.Config}}. This can be hardcoded in the configuration file or obtained from environment variables. For environment variable injection, reference using {{ env "ENV_VAR_NAME" }}.
5. Tool Configuration
Tool configuration is used to define specific API call rules. Each parameter can set a default value (default), which will be automatically used when the parameter is not provided in the MCP request.5.1 Request Parameter Assembly
When requesting the target service, parameter assembly is involved. Currently there are several sources:.Config: Extract values from service-level configuration.Args: Extract values directly from request parameters.Request: Values extracted from the request, including request headers.Request.Headers, request body.Request.Body, etc.
header: Parameter will be placed in request headersquery: Parameter will be placed in URL query stringpath: Parameter will be placed in URL pathbody: Parameter will be placed in JSON format request bodyform-data: Parameter will be placed in multipart/form-data format request body, for file upload scenarios
string: String typenumber: Number typeboolean: Boolean typearray: Array type, needs to be used withitemsto define array element typesobject: Object type, can usepropertiesto define object structure
array type parameters, detailed element structures can be defined:
form-data as parameter position, no need to specify requestBody, the system will automatically assemble parameters into multipart/form-data format.
Additionally, header and query parameters are auto-injected into the downstream request (Header key equals the parameter name; Query is appended to the URL). For example:
Client (MCP Request)
Example arguments from MCP client:
MCP Gateway
headeris auto-written to downstream headers (key = param name)queryis auto-appended to the URL query stringform-datais auto-assembled as multipart/form-data
Downstream Service (HTTP Request)
Actual request sent to downstream:
requestBody, for example:
endpoint (target address) can also use the above sources to extract values, such as http://localhost:5236/users/{{.Args.email}}/preferences which extracts values from request parameters.
5.2 Response Parameter Assembly
Response body assembly is similar to request body assembly:.Response.Data: Values extracted from response, response must be in JSON format to be extractable.Response.Body: Directly pass through the entire response body, ignoring response content format and directly passing to client
.Response, for example:
Configuration Storage
Gateway proxy configuration can be stored in the following two ways:Database Storage (Recommended)
- Supports SQLite3, PostgreSQL, MySQL
- Each configuration stored as a record
- Supports dynamic updates and hot reloading
File Storage
- Each configuration stored separately as a YAML file
- Similar to Nginx vhost configuration method
- File name recommended to use service name, such as
mock-server.yaml
MCP Service Proxy Configuration
In addition to proxying HTTP services, MCP Gateway also supports proxying MCP services. Currently, stdio, SSE, and streamable-http three transport protocols are all supported.Configuration Example
The following is a complete MCP service proxy configuration example:Configuration Explanation
1. MCP Service Types
MCP Gateway supports the following three types of MCP service proxies:stdio Type
stdio Type
- Communicate with MCP service processes via standard input/output
- Suitable for MCP services that need local startup, such as third-party SDKs
- Configuration parameters include
command,args, andenv
SSE Type
SSE Type
- Forward MCP client requests to upstream services supporting SSE
- Suitable for existing MCP services supporting SSE protocol
- Only need to configure
urlparameter pointing to upstream SSE service address
streamable-http Type
streamable-http Type
- Forward MCP client requests to upstream services supporting streamable HTTP
- Suitable for existing upstream services supporting MCP protocol
- Only need to configure
urlparameter pointing to upstream MCP service address
2. stdio Type Configuration
stdio type MCP service configuration example:env field, supporting value extraction from requests, for example {{.Request.Headers.Apikey}} means extract the Apikey value from request headers.
3. SSE Type Configuration
SSE type MCP service configuration example:4. streamable-http Type Configuration
streamable-http type MCP service configuration example:5. Routing Configuration
For MCP service proxy, routing configuration is similar to HTTP service proxy. CORS should be configured according to actual situation (usually production environments generally do not enable cross-origin):For MCP services,
Mcp-Session-Id in request and response headers must be supported, otherwise clients cannot use it normally.Advanced Configuration
Notifier Configuration
Notifier is used to configure reload notifications, supporting multiple methods:Signal Notification
Signal Notification
Notify via system signals, suitable for single-machine deployment
API Notification
API Notification
Notify via HTTP API, suitable for remote management
Redis Notification
Redis Notification
Notify via Redis publish/subscribe, suitable for cluster deployment
Environment Variable Injection
Environment variables can be used in configuration, supporting default values:Template Functions
In request and response body templates, template functions can be used to handle complex data:toJSON
toJSON
Convert objects or arrays to JSON strings for handling complex data structures
Direct Use
Direct Use
For simple arrays and objects, variables can be used directly
Using the
toJSON function ensures complex objects and arrays are correctly serialized to JSON format, especially suitable for nested structures and data containing special characters.Complex Parameter Processing Example
The following is a complete example of handling complex parameters, showing how to define and use object and array type parameters:File Upload Processing
Supports file upload scenarios:Best Practices
Security
Security
- Use environment variables to store sensitive information (such as database passwords, API keys)
- Limit CORS Origins in production environments, avoid using ”*”
- Enable OAuth2 authentication and appropriate authorization mechanisms
- Regularly rotate API keys and tokens
- Use encrypted Redis connections to store session data
Performance
Performance
- Set reasonable timeout and reload intervals
- Use Redis clusters to improve session storage performance
- Choose appropriate log levels, avoid excessive debug logs
- Use connection pools to reduce connection overhead
- Cache frequently called APIs
- Avoid complex calculations in templates
Maintainability
Maintainability
- Use meaningful tool and service names
- Add detailed description information
- Keep configuration files clean and readable
- Configure log rotation to avoid disk space shortage
- Monitor PID files and process status
- Set appropriate notifier types for configuration management convenience
- Regularly check and update configurations
Testing
Testing
- Thoroughly test configurations in development environments
- Use mock services for integration testing
- Verify all parameters and response formats
- Test error handling and edge cases
Configuration Validation
Before applying configuration, it is recommended to perform the following validations:1
Syntax Check
Ensure YAML syntax is correct with no indentation errors
2
Environment Variable Verification
Check if all required environment variables are set
3
Storage Connection Test
Verify database or Redis connection configuration is correct
4
Reference Verification
Check if all reference relationships are correct, such as server name matching
5
Template Verification
Verify Go Template syntax and variable references
6
Endpoint Testing
Ensure all endpoints are accessible
7
Permission Verification
Ensure PID file path has write permissions
For more information on Go Template usage, please refer to Template Usage Guide.