Skip to main content

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

MCP Gateway service listening port, default 5235
Process ID file path for process management and reloading
Configuration reload interval, default 600s
Whether to enable automatic configuration reloading
A configuration can be treated as a namespace, recommended to distinguish by service or domain. A service contains many API interfaces, each API interface corresponds to a Tool.
  • name: Proxy service name, globally unique, used to identify different proxy services
  • tenant: Tenant identifier for data isolation and permission management in multi-tenant scenarios

2. Routing Configuration

Routing configuration is used to define request forwarding rules:
Currently, by default, 3 endpoints are derived based on 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:
Service-level configuration can be referenced in tools via {{.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:
  1. .Config: Extract values from service-level configuration
  2. .Args: Extract values directly from request parameters
  3. .Request: Values extracted from the request, including request headers .Request.Headers, request body .Request.Body, etc.
Parameter position (position) supports the following types:
  • header: Parameter will be placed in request headers
  • query: Parameter will be placed in URL query string
  • path: Parameter will be placed in URL path
  • body: Parameter will be placed in JSON format request body
  • form-data: Parameter will be placed in multipart/form-data format request body, for file upload scenarios
Parameter type (type) supports the following types:
  • string: String type
  • number: Number type
  • boolean: Boolean type
  • array: Array type, needs to be used with items to define array element types
  • object: Object type, can use properties to define object structure
For complex array type parameters, detailed element structures can be defined:
When using 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

  • header is auto-written to downstream headers (key = param name)
  • query is auto-appended to the URL query string
  • form-data is auto-assembled as multipart/form-data
Tool config snippet:

Downstream Service (HTTP Request)

Actual request sent to downstream:
For JSON format request body, assembly is needed in requestBody, for example:
Including 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:
  1. .Response.Data: Values extracted from response, response must be in JSON format to be extractable
  2. .Response.Body: Directly pass through the entire response body, ignoring response content format and directly passing to client
Both extract values via .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:
  • 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, and env
  • Forward MCP client requests to upstream services supporting SSE
  • Suitable for existing MCP services supporting SSE protocol
  • Only need to configure url parameter pointing to upstream SSE service address
  • Forward MCP client requests to upstream services supporting streamable HTTP
  • Suitable for existing upstream services supporting MCP protocol
  • Only need to configure url parameter pointing to upstream MCP service address

2. stdio Type Configuration

stdio type MCP service configuration example:
Environment variables can be set via the 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:
Notify via system signals, suitable for single-machine deployment
Notify via HTTP API, suitable for remote management
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:
Convert objects or arrays to JSON strings for handling complex data structures
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

  • 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
  • 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
  • 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
  • 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.