AgentsCLI Tools

mcp-gateway

View as MarkdownOpen in Claude

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:

EndpointMethodAuthDescription
/healthGETNoHealth check with status and timestamp
/servicesGETYesList available MCP services
/services/<name>/toolsGETYesList tools for a specific service
/services/<name>/callPOSTYesCall a tool on a service
/sessionsGETYesList active sessions
/sessions/<id>DELETEYesTerminate 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