trackmcp
Back to directory
Timandes

mcp-gateway

View on GitHub

MCP Gateway - translate MCP tool-callings to HTTP requests

1 stars PythonOthers Updated Jul 22, 2025

Documentation

MCP Gateway

MCP (Model Context Protocol) Gateway can translate MCP tool callings to traditional HTTP API requests. It can provide a configurable way to get existing HTTP API to MCP territory.

Getting Started

Create config file from `config.example.yaml`:

shell
$ cp config.example.yaml config.yaml

Edit `config.yaml` file, map all APIs to MCP tools.

Then start launch it with SSE transport:

shell
$ uv run mcp-gateway
INFO:     Started server process [15400]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:3001 (Press CTRL+C to quit)

Default is 3001.

Server Control

Change Port

Provide parameter `--port=` in command line will change the port to SSE transport.

Launch gateway with port 3002:

shell
$ uv run mcp-gateway --port=3002
INFO:     Started server process [15400]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:3002 (Press CTRL+C to quit)

stdio Transport

Provide parameter `--transport=stdio` in command line will change the transport to stdio.

E.G.:

shell
$ uv run mcp-gateway --transport=stdio

It's meaningless to manually launch gateway in stdio transport. You can configure in Cursor or Cline like:

json
{
    "mcpServers": {
        "mcp-gateway": {
          "command": "uv",
          "args": ["run", "mcp-gateway", "--transport=stdio"]
        }
      }
}

Or MCP Inspector with form values:

ItemValue
Transport TypeSTDIO
Commanduv
Argumentsrun mcp-gateway --transport=stdio

Configuration File

There is two parts in configuration YAML, `server` and `tools`. `server` defines the basic info for gateway server use. `tools` defines the mapping from single MCP tool to HTTP API request.

yaml
server:
  name: rest-amap-server
  config:
    apiKey: foo
tools:
- name: maps-geo
  description: "将详细的结构化地址转换为经纬度坐标。支持对地标性名胜景区、建筑物名称解析为经纬度坐标"
  args:
  - name: address
    description: "待解析的结构化地址信息"
    required: true
  - name: city
    description: "指定查询的城市"
    required: false
  requestTemplate:
    url: "https://restapi.amap.com/v3/geocode/geo?key={{.config.apiKey}}&address={{.args.address}}&city={{.args.city}}&source=ts_mcp"
    method: GET
    headers:
    - key: x-api-key
      value: "{{.config.apiKey}}"
    - key: Content-Type
      value: application/json
  responseTemplate:
    body: |
      # 地理编码信息
      {{- range $index, $geo := .Geocodes }}
      ## 地点 {{add $index 1}}

      - **国家**: {{ $geo.Country }}
      - **省份**: {{ $geo.Province }}
      - **城市**: {{ $geo.City }}
      - **城市代码**: {{ $geo.Citycode }}
      - **区/县**: {{ $geo.District }}
      - **街道**: {{ $geo.Street }}
      - **门牌号**: {{ $geo.Number }}
      - **行政编码**: {{ $geo.Adcode }}
      - **坐标**: {{ $geo.Location }}
      - **级别**: {{ $geo.Level }}
      {{- end }}

Server

ItemDescription
nameServer name
configKey/Value pairs that can be referenced by var `{{.config.xxx}}` in templates

Tools

`tools` is list of MCP tools mapping. Single tool props. are defined as follows:

ItemDescription
nameTool name (Function name), which is provided to LLM.
descriptionTool description through which LLM can understand what the tool could do.
argsArguments of tool (Function arguments).
requestTemplateRequest mapping to target HTTP API.
responseTemplateResponse mapping for response of target HTTP API.

Single argument props. are defined as follows:

ItemTypeDescription
nameArgument name, which is provided to LLM.
descriptionArgument description through which LLM can understand and decide what value should be filled.
requiredBooleanRequired argument or not.

Request template props. are defined as follows:

ItemDescription
methodHTTP method
urlTarget HTTP API url template
headersHTTP headers

HTTP headers are defined as follows:

ItemDescription
keyHeader key
valueHeader value template

Response template props are defined as follows:

ItemDescription
bodyResponse body template

Contribution

All kinds of contribution are welcomed.

Frequently asked questions

What is mcp-gateway?

mcp-gateway is MCP Gateway - translate MCP tool-callings to HTTP requests

How do I install mcp-gateway?

Open the GitHub repository and follow its README. Most MCP servers are added to your client's MCP config, then called by your agent.

Is mcp-gateway open source?

Yes — it is hosted on GitHub at https://github.com/Timandes/mcp-gateway and has 1 stars.

Related MCP tools

Run your own MCP server? See who uses it and what to fix.

Measure it with TrackMCP