mcp-gateway

The mcp-gateway command starts an HTTP/HTTPS server that bridges Model Context Protocol (MCP) servers with SignalWire SWAIG functions. It manages sessions, handles authentication, translates between MCP tool calls and SWAIG format, and provides rate limiting and security headers.

$ mcp-gateway [-c CONFIG_PATH]

-c, --config

stringDefaults to config.json

Path to the JSON configuration file.

Configuration

The gateway is configured via a JSON file. All settings support environment variable substitution using ${VAR_NAME|default} syntax via ConfigLoader.

Minimal Configuration

1 {
2   "server": {
3     "host": "0.0.0.0",
4     "port": 8080,
5     "auth_user": "admin",
6     "auth_password": "${MCP_AUTH_PASSWORD|changeme}"
7   },
8   "services": {
9     "my-service": {
10       "command": ["python3", "./my_mcp_server.py"],
11       "description": "My MCP service",
12       "enabled": true
13     }
14   }
15 }

Full Configuration Reference

1 {
2   "server": {
3     "host": "0.0.0.0",
4     "port": 8080,
5     "auth_user": "admin",
6     "auth_password": "${MCP_AUTH_PASSWORD}",
7     "auth_token": "${MCP_BEARER_TOKEN}"
8   },
9   "services": {
10     "service-name": {
11       "command": ["python3", "./server.py"],
12       "description": "Service description",
13       "enabled": true,
14       "sandbox_config": {
15         "enabled": true,
16         "resource_limits": true,
17         "restricted_env": true
18       }
19     }
20   },
21   "session": {
22     "default_timeout": 300,
23     "max_sessions_per_service": 100,
24     "cleanup_interval": 60
25   },
26   "rate_limiting": {
27     "default_limits": ["200 per day", "50 per hour"],
28     "tools_limit": "30 per minute",
29     "call_limit": "10 per minute",
30     "session_delete_limit": "20 per minute",
31     "storage_uri": "memory://"
32   },
33   "logging": {
34     "level": "INFO",
35     "file": "/var/log/mcp-gateway.log"
36   }
37 }

Configuration Sections

server

server.host

stringDefaults to 0.0.0.0

Bind address for the gateway server.

server.port

intDefaults to 8080

Port for the gateway server.

server.auth_user

string

Username for HTTP Basic Authentication on all protected endpoints.

server.auth_password

string

Password for HTTP Basic Authentication.

server.auth_token

string

Bearer token for token-based authentication. If set, clients can authenticate with Authorization: Bearer <token> as an alternative to Basic Auth.

services

Each key in the services object defines an MCP server that the gateway can spawn and manage.

services.<name>.command

list[str]Required

The command and arguments to start the MCP server process.

services.<name>.description

string

Human-readable description of the service.

services.<name>.enabled

boolDefaults to true

Whether the service is active. Disabled services are not started or listed.

services.<name>.sandbox_config

object

Sandbox configuration for process isolation. Controls resource limits and environment restrictions for the spawned MCP process.

session

session.default_timeout

intDefaults to 300

Default session timeout in seconds. Sessions are cleaned up after this duration of inactivity.

session.max_sessions_per_service

intDefaults to 100

Maximum concurrent sessions per MCP service.

session.cleanup_interval

intDefaults to 60

Interval in seconds between session cleanup sweeps.

rate_limiting

rate_limiting.default_limits

list[str]Defaults to ["200 per day", "50 per hour"]

Default rate limits applied to all endpoints.

rate_limiting.tools_limit

stringDefaults to 30 per minute

Rate limit for the tool listing endpoint.

rate_limiting.call_limit

stringDefaults to 10 per minute

Rate limit for tool call endpoints.

rate_limiting.session_delete_limit

stringDefaults to 20 per minute

Rate limit for session deletion endpoints.

rate_limiting.storage_uri

stringDefaults to memory://

Storage backend for rate limit counters. Use memory:// for in-process storage or a Redis URI for distributed deployments.

API Endpoints

The gateway exposes the following HTTP endpoints:

Endpoint	Method	Auth	Description
`/health`	GET	No	Health check with status and timestamp
`/services`	GET	Yes	List available MCP services
`/services/<name>/tools`	GET	Yes	List tools for a specific service
`/services/<name>/call`	POST	Yes	Call a tool on a service
`/sessions`	GET	Yes	List active sessions
`/sessions/<id>`	DELETE	Yes	Terminate a specific session

Calling a Tool

$ curl -X POST "http://localhost:8080/services/my-service/call" \
>   -u admin:password \
>   -H "Content-Type: application/json" \
>   -d '{
>     "tool": "my_tool",
>     "session_id": "call-123",
>     "arguments": {"param": "value"},
>     "timeout": 300
>   }'

SSL Support

If a certificate file exists at certs/server.pem, the gateway automatically enables HTTPS. The gateway also uses SecurityConfig for security headers (X-Content-Type-Options, X-Frame-Options, HSTS, etc.).

Example

$ # Start with default config.json
$ mcp-gateway
$ 
$ # Start with custom config path
$ mcp-gateway -c /etc/mcp-gateway/config.json

1	{
2	"server": {
3	"host": "0.0.0.0",
4	"port": 8080,
5	"auth_user": "admin",
6	"auth_password": "${MCP_AUTH_PASSWORD\|changeme}"
7	},
8	"services": {
9	"my-service": {
10	"command": ["python3", "./my_mcp_server.py"],
11	"description": "My MCP service",
12	"enabled": true
13	}
14	}
15	}

$	curl -X POST "http://localhost:8080/services/my-service/call" \
>	-u admin:password \
>	-H "Content-Type: application/json" \
>	-d '{
>	"tool": "my_tool",
>	"session_id": "call-123",
>	"arguments": {"param": "value"},
>	"timeout": 300
>	}'

$	# Start with default config.json
$	mcp-gateway
$
$	# Start with custom config path
$	mcp-gateway -c /etc/mcp-gateway/config.json