Gateway Proxy Configuration

HTTP Service Proxy Configuration

The following is a specific configuration example for HTTP service proxy, including routing, tools and other configurations:

name: "mock-server"              # Proxy service name, globally unique
tenant: "default"                # Tenant identifier for multi-tenant scenarios

# Routing configuration
routers:
  - server: "mock-server"       # Service name
    prefix: "/gateway/user"         # Route prefix, globally unique, non-repeatable, recommended to distinguish prefixes by service or domain+module

    # CORS configuration
    cors:
      allowOrigins:             # Development and test environments can be fully open, production should be opened as needed. (Most MCP Clients do not need to open cross-origin)
        - "*"
      allowMethods:             # Allowed request methods, open as needed, for MCP (SSE and Streamable) usually only these 3 methods are needed
        - "GET"
        - "POST"
        - "PUT"
        - "OPTIONS"
      allowHeaders:
        - "Content-Type"        # Must be allowed
        - "Authorization"       # Required for authentication needs to support carrying this key in requests
        - "Mcp-Session-Id"      # For MCP, must support carrying this key in requests, otherwise Streamable HTTP cannot be used normally
        - "mcp-protocol-version" # MCP protocol version header for protocol version negotiation
      exposeHeaders:
        - "Mcp-Session-Id"      # For MCP, when cross-origin is enabled, this key must be exposed, otherwise Streamable HTTP cannot be used normally
        - "mcp-protocol-version" # MCP protocol version header
      allowCredentials: true    # Whether to add Access-Control-Allow-Credentials: true header

# Service configuration
servers:
  - name: "mock-server"               # Service name, must match server in routers
    description: "Mock User Service"  # Service description
    allowedTools:                     # List of allowed tools (subset of tools)
      - "register_user"
      - "get_user_by_email"
      - "update_user_preferences"
      - "update_user_avatar"
    config:                                           # Service-level configuration, can be referenced in tools via {{.Config}}
      Cookie: 123                                     # Hardcoded configuration
      Authorization: 'Bearer {{ env "AUTH_TOKEN" }}'  # Configuration from environment variables, usage is '{{ env "ENV_VAR_NAME" }}'

# Tool configuration
tools:
  - name: "register_user"                                   # Tool name
    description: "Register a new user"                      # Tool description
    method: "POST"                                          # HTTP method for requesting target (upstream, backend) service
    endpoint: "http://localhost:5236/users"                 # Target service address
    headers:                                                # Request header configuration for carrying headers when requesting target service
      Content-Type: "application/json"                      # Hardcoded request header
      Authorization: "{{.Config.Authorization}}"            # Use value from service configuration
      Cookie: "{{.Config.Cookie}}"                          # Use value from service configuration
    args:                         # Parameter configuration
      - name: "username"          # Parameter name
        position: "body"          # Parameter position: header, query, path, body, form-data
        required: true            # Whether parameter is required
        type: "string"            # Parameter type
        description: "Username"   # Parameter description
        default: ""               # Default value
      - name: "email"
        position: "body"
        required: true
        type: "string"
        description: "Email"
        default: ""
    requestBody: |-                       # Request body template for dynamically generating request body, e.g., values extracted from parameters (MCP request arguments)
      {
        "username": "{{.Args.username}}",
        "email": "{{.Args.email}}"
      }
    responseBody: |-                      # Response body template for dynamically generating response body, e.g., values extracted from response
      {
        "id": "{{.Response.Data.id}}",
        "username": "{{.Response.Data.username}}",
        "email": "{{.Response.Data.email}}",
        "createdAt": "{{.Response.Data.createdAt}}"
      }

  - name: "get_user_by_email"
    description: "Get user by email"
    method: "GET"
    endpoint: "http://localhost:5236/users/email/{{.Args.email}}"
    args:
      - name: "email"
        position: "path"
        required: true
        type: "string"
        description: "Email"
        default: ""
    responseBody: |-
      {
        "id": "{{.Response.Data.id}}",
        "username": "{{.Response.Data.username}}",
        "email": "{{.Response.Data.email}}",
        "createdAt": "{{.Response.Data.createdAt}}"
      }

  - name: "update_user_preferences"
    description: "Update user preferences"
    method: "PUT"
    endpoint: "http://localhost:5236/users/{{.Args.email}}/preferences"
    headers:
      Content-Type: "application/json"
      Authorization: "{{.Request.Headers.Authorization}}"
      Cookie: "{{.Config.Cookie}}"
    args:
      - name: "email"
        position: "path"
        required: true
        type: "string"
        description: "Email"
        default: ""
      - name: "isPublic"
        position: "body"
        required: true
        type: "boolean"
        description: "Whether the user profile is public"
        default: "false"
      - name: "showEmail"
        position: "body"
        required: true
        type: "boolean"
        description: "Whether to show email in profile"
        default: "true"
      - name: "theme"
        position: "body"
        required: true
        type: "string"
        description: "User interface theme"
        default: "light"
      - name: "tags"
        position: "body"
        required: true
        type: "array"
        items:
          type: "string"
          enum: ["developer", "designer", "manager", "tester"]
        description: "User role tags"
        default: "[]"
      - name: "settings"
        position: "body"
        required: false
        type: "object"
        description: "User custom settings as key-value pairs"
        default: "{}"
      - name: "notifications"
        position: "body"
        required: false
        type: "array"
        description: "User notification preferences"
        items:
          type: "object"
          properties:
            type:
              type: "string"
              description: "Notification type (email, push, sms)"
            channel:
              type: "string"
              description: "Notification channel (marketing, system, security)"
            enabled:
              type: "boolean"
              description: "Whether this notification is enabled"
            frequency:
              type: "number"
              description: "Notification frequency (0: realtime, 1: daily, 2: weekly, 3: monthly)"
        default: "[]"
    requestBody: |-
      {
        "isPublic": {{.Args.isPublic}},
        "showEmail": {{.Args.showEmail}},
        "theme": "{{.Args.theme}}",
        "tags": {{.Args.tags}},
        "settings": {{ toJSON .Args.settings }},
        "notifications": {{ .Args.notifications }}
      }
    responseBody: |-
      {
        "id": "{{.Response.Data.id}}",
        "username": "{{.Response.Data.username}}",
        "email": "{{.Response.Data.email}}",
        "createdAt": "{{.Response.Data.createdAt}}",
        "preferences": {
          "isPublic": {{.Response.Data.preferences.isPublic}},
          "showEmail": {{.Response.Data.preferences.showEmail}},
          "theme": "{{.Response.Data.preferences.theme}}",
          "tags": {{.Response.Data.preferences.tags}},
          "settings": {{ toJSON .Response.Data.preferences.settings }},
          "notifications": {{ toJSON .Response.Data.preferences.notifications }}
        }
      }

  - name: "update_user_avatar"
    description: "Update user avatar using a URL via multipart form"
    method: "POST"
    endpoint: "http://localhost:5236/users/{{.Args.email}}/avatar"
    headers:
      Authorization: "{{.Request.Headers.Authorization}}"
      Cookie: "{{.Config.Cookie}}"
    args:
      - name: "email"
        position: "path"
        required: true
        type: "string"
        description: "Email of the user"
        default: ""
      - name: "url"
        position: "form-data"
        required: true
        type: "string"
        description: "The avatar image URL"
        default: ""
    responseBody: |-
      {
        "message": "{{.Response.Data.message}}",
        "avatarUrl": "{{.Response.Data.avatarUrl}}"
      }

Configuration Explanation

1. Basic Configuration

port

pid

reload_interval

reload_switch

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:

routers:
  - server: "mock-server"       # Service name, must match name in servers
    prefix: "/gateway/user"         # Route prefix, globally unique, non-repeatable

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:

cors:
  allowOrigins:             # Development and test environments can be fully open, production should be opened as needed. (Most MCP Clients do not need to open cross-origin)
    - "*"
  allowMethods:             # Allowed request methods, open as needed, for MCP (SSE and Streamable) usually only these 3 methods are needed
    - "GET"
    - "POST"
    - "OPTIONS"
  allowHeaders:
    - "Content-Type"        # Must be allowed
    - "Authorization"       # Required for authentication needs to support carrying this key in requests
    - "Mcp-Session-Id"      # For MCP, must support carrying this key in requests, otherwise Streamable HTTP cannot be used normally
  exposeHeaders:
    - "Mcp-Session-Id"      # For MCP, when cross-origin is enabled, this key must be exposed, otherwise Streamable HTTP cannot be used normally
  allowCredentials: true    # Whether to add Access-Control-Allow-Credentials: true header

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:

servers:
  - name: "mock-server"               # Service name, must match server in routers
    namespace: "user-service"         # Service namespace for service grouping
    description: "Mock User Service"  # Service description
    allowedTools:                     # List of allowed tools (subset of tools)
      - "register_user"
      - "get_user_by_email"
      - "update_user_preferences"
    config:                                           # Service-level configuration, can be referenced in tools via {{.Config}}
      Cookie: 123                                     # Hardcoded configuration
      Authorization: 'Bearer {{ env "AUTH_TOKEN" }}'  # Configuration from environment variables, usage is '{{ env "ENV_VAR_NAME" }}'

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:

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

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:

- name: "notifications"
  position: "body"
  required: false
  type: "array"
  description: "User notification preferences"
  items:
    type: "object"
    properties:
      type:
        type: "string"
        description: "Notification type (email, push, sms)"
      enabled:
        type: "boolean"
        description: "Whether this notification is enabled"
  default: "[]"

When using form-data as parameter position, no need to specify requestBody, the system will automatically assemble parameters into multipart/form-data format. For JSON format request body, assembly is needed in requestBody, for example:

    requestBody: |-
      {
        "isPublic": {{.Args.isPublic}},
        "showEmail": {{.Args.showEmail}},
        "theme": "{{.Args.theme}}",
        "tags": {{.Args.tags}}
      }

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:

.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

Both extract values via .Response, for example:

    responseBody: |-
      {
        "id": "{{.Response.Data.id}}",
        "username": "{{.Response.Data.username}}",
        "email": "{{.Response.Data.email}}",
        "createdAt": "{{.Response.Data.createdAt}}"
      }

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:

name: "proxy-mcp-exp"
tenant: "default"

routers:
  - server: "amap-maps"
    prefix: "/gateway/stdio-proxy"
    cors:
      allowOrigins:
        - "*"
      allowMethods:
        - "GET"
        - "POST"
        - "OPTIONS"
      allowHeaders:
        - "Content-Type"
        - "Authorization"
        - "Mcp-Session-Id"
      exposeHeaders:
        - "Mcp-Session-Id"
      allowCredentials: true
  - server: "mock-user-sse"
    prefix: "/gateway/sse-proxy"
    cors:
      allowOrigins:
        - "*"
      allowMethods:
        - "GET"
        - "POST"
        - "OPTIONS"
      allowHeaders:
        - "Content-Type"
        - "Authorization"
        - "Mcp-Session-Id"
      exposeHeaders:
        - "Mcp-Session-Id"
      allowCredentials: true
  - server: "mock-user-mcp"
    prefix: "/gateway/streamable-http-proxy"
    cors:
      allowOrigins:
        - "*"
      allowMethods:
        - "GET"
        - "POST"
        - "OPTIONS"
      allowHeaders:
        - "Content-Type"
        - "Authorization"
        - "Mcp-Session-Id"
      exposeHeaders:
        - "Mcp-Session-Id"
      allowCredentials: true

mcpServers:
  - type: "stdio"
    name: "amap-maps"
    command: "npx"
    args:
      - "-y"
      - "@amap/amap-maps-mcp-server"
    env:
      AMAP_MAPS_API_KEY: "{{.Request.Headers.Apikey}}"

  - type: "sse"
    name: "mock-user-sse"
    url: "http://localhost:3000/gateway/user/sse"

  - type: "streamable-http"
    name: "mock-user-mcp"
    url: "http://localhost:3000/gateway/user/mcp"

Configuration Explanation

1. MCP Service Types

MCP Gateway supports the following three types of MCP service proxies:

stdio Type

SSE Type

streamable-http Type

2. stdio Type Configuration

stdio type MCP service configuration example:

mcpServers:
  - type: "stdio"
    name: "amap-maps"                                   # Service name
    command: "npx"                                      # Command to execute
    args:                                               # Command arguments
      - "-y"
      - "@amap/amap-maps-mcp-server"
    env:                                                # Environment variables
      AMAP_MAPS_API_KEY: "{{.Request.Headers.Apikey}}"  # Extract value from request headers

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:

mcpServers:
  - type: "sse"
    name: "mock-user-sse"                           # Service name
    url: "http://localhost:3000/gateway/user/sse"   # Upstream SSE service address, usually ends with /sse, actual depends on upstream service

4. streamable-http Type Configuration

streamable-http type MCP service configuration example:

mcpServers:
  - type: "streamable-http"
    name: "mock-user-mcp"                           # Service name
    url: "http://localhost:3000/gateway/user/mcp"   # Upstream MCP service address, usually ends with /mcp, actual depends on upstream service

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):

routers:
  - server: "amap-maps"               # Service name, must match name in mcpServers
    prefix: "/gateway/stdio-proxy"    # Route prefix, globally unique
    cors:
      allowOrigins:
        - "*"
      allowMethods:
        - "GET"
        - "POST"
        - "OPTIONS"
      allowHeaders:
        - "Content-Type"
        - "Authorization"
        - "Mcp-Session-Id"        # MCP service must include this header
      exposeHeaders:
        - "Mcp-Session-Id"        # MCP service must expose this header
      allowCredentials: true

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

API Notification

Redis Notification

Environment Variable Injection

Environment variables can be used in configuration, supporting default values:

# Basic syntax
port: ${MCP_GATEWAY_PORT:5235}  # Use environment variable, default value 5235

# String format
logger:
  level: "${LOGGER_LEVEL:info}"  # Use environment variable, default value info

# Use in service configuration
config:
  ApiKey: '{{ env "API_KEY" }}'
  BaseUrl: '{{ env "API_BASE_URL" "http://localhost:8080" }}'  # With default value

Template Functions

In request and response body templates, template functions can be used to handle complex data:

toJSON

Convert objects or arrays to JSON strings for handling complex data structures

requestBody: |-
  {
    "settings": {{ toJSON .Args.settings }},
    "notifications": {{ toJSON .Args.notifications }}
  }

Direct Use

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:

args:
  - name: "settings"
    position: "body"
    required: false
    type: "object"
    description: "User custom settings as key-value pairs"
    default: "{}"
  - name: "notifications"
    position: "body"
    required: false
    type: "array"
    description: "User notification preferences"
    items:
      type: "object"
      properties:
        type:
          type: "string"
          description: "Notification type (email, push, sms)"
        channel:
          type: "string"
          description: "Notification channel (marketing, system, security)"
        enabled:
          type: "boolean"
          description: "Whether this notification is enabled"
        frequency:
          type: "number"
          description: "Notification frequency (0: realtime, 1: daily, 2: weekly, 3: monthly)"
    default: "[]"

requestBody: |-
  {
    "settings": {{ toJSON .Args.settings }},
    "notifications": {{ .Args.notifications }}
  }

responseBody: |-
  {
    "settings": {{ toJSON .Response.Data.preferences.settings }},
    "notifications": {{ toJSON .Response.Data.preferences.notifications }}
  }

File Upload Processing

Supports file upload scenarios:

args:
  - name: "file"
    position: "form-data"
    required: true
    type: "string"
    description: "File to upload"
  - name: "description"
    position: "form-data"
    required: false
    type: "string"
    description: "File description"

Best Practices

Security

Performance

Maintainability

Testing

Configuration Validation

Before applying configuration, it is recommended to perform the following validations:

Syntax Check

Ensure YAML syntax is correct with no indentation errors

Environment Variable Verification

Check if all required environment variables are set

Storage Connection Test

Verify database or Redis connection configuration is correct

Reference Verification

Check if all reference relationships are correct, such as server name matching

Template Verification

Verify Go Template syntax and variable references

Endpoint Testing

Ensure all endpoints are accessible

Permission Verification

Ensure PID file path has write permissions

For more information on Go Template usage, please refer to Template Usage Guide.

Getting Started

Deployment

Configuration

Web Configuration

Client Usage

Development

API Documentation

Endpoint Examples

HTTP Service Proxy Configuration

Configuration Explanation

1. Basic Configuration

2. Routing Configuration

3. CORS Configuration

4. Service Configuration

5. Tool Configuration

5.1 Request Parameter Assembly

5.2 Response Parameter Assembly

Configuration Storage

Database Storage (Recommended)

File Storage

MCP Service Proxy Configuration

Configuration Example

Configuration Explanation

1. MCP Service Types

2. stdio Type Configuration

3. SSE Type Configuration

4. streamable-http Type Configuration

5. Routing Configuration

Advanced Configuration

Notifier Configuration

Environment Variable Injection

Template Functions

Complex Parameter Processing Example

File Upload Processing

Best Practices

Configuration Validation

Getting Started

Deployment

Configuration

Web Configuration

Client Usage

Development

API Documentation

Endpoint Examples

​HTTP Service Proxy Configuration

​Configuration Explanation

​1. Basic Configuration

​2. Routing Configuration

​3. CORS Configuration

​4. Service Configuration

​5. Tool Configuration

​5.1 Request Parameter Assembly

​5.2 Response Parameter Assembly

​Configuration Storage

Database Storage (Recommended)

File Storage

​MCP Service Proxy Configuration

​Configuration Example

​Configuration Explanation

​1. MCP Service Types

​2. stdio Type Configuration

​3. SSE Type Configuration

​4. streamable-http Type Configuration

​5. Routing Configuration

​Advanced Configuration

​Notifier Configuration

​Environment Variable Injection

​Template Functions

​Complex Parameter Processing Example

​File Upload Processing

​Best Practices

​Configuration Validation

HTTP Service Proxy Configuration

Configuration Explanation

1. Basic Configuration

2. Routing Configuration

3. CORS Configuration

4. Service Configuration

5. Tool Configuration

5.1 Request Parameter Assembly

5.2 Response Parameter Assembly

Configuration Storage

MCP Service Proxy Configuration

Configuration Example

Configuration Explanation

1. MCP Service Types

2. stdio Type Configuration

3. SSE Type Configuration

4. streamable-http Type Configuration

5. Routing Configuration

Advanced Configuration

Notifier Configuration

Environment Variable Injection

Template Functions

Complex Parameter Processing Example

File Upload Processing

Best Practices

Configuration Validation