> For a complete index of all SignalWire documentation pages, fetch https://signalwire.com/docs/llms.txt

# mcp-gateway

> HTTP bridge between MCP servers and SignalWire SWAIG functions.

[configloader]: /docs/server-sdks/reference/python/agents/configuration/config-loader

[securityconfig]: /docs/server-sdks/reference/python/agents/configuration/security-config

The `mcp-gateway` command starts an HTTP/HTTPS server that bridges
[Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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.

```bash
mcp-gateway [-c CONFIG_PATH]
```

**`-c, --config`** `string` — default: 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`][configloader].

### Minimal Configuration

```json
{
  "server": {
    "host": "0.0.0.0",
    "port": 8080,
    "auth_user": "admin",
    "auth_password": "${MCP_AUTH_PASSWORD|changeme}"
  },
  "services": {
    "my-service": {
      "command": ["python3", "./my_mcp_server.py"],
      "description": "My MCP service",
      "enabled": true
    }
  }
}
```

### Full Configuration Reference

```json
{
  "server": {
    "host": "0.0.0.0",
    "port": 8080,
    "auth_user": "admin",
    "auth_password": "${MCP_AUTH_PASSWORD}",
    "auth_token": "${MCP_BEARER_TOKEN}"
  },
  "services": {
    "service-name": {
      "command": ["python3", "./server.py"],
      "description": "Service description",
      "enabled": true,
      "sandbox_config": {
        "enabled": true,
        "resource_limits": true,
        "restricted_env": true
      }
    }
  },
  "session": {
    "default_timeout": 300,
    "max_sessions_per_service": 100,
    "cleanup_interval": 60
  },
  "rate_limiting": {
    "default_limits": ["200 per day", "50 per hour"],
    "tools_limit": "30 per minute",
    "call_limit": "10 per minute",
    "session_delete_limit": "20 per minute",
    "storage_uri": "memory://"
  },
  "logging": {
    "level": "INFO",
    "file": "/var/log/mcp-gateway.log"
  }
}
```

## Configuration Sections

### server

**`server.host`** `string` — default: 0.0.0.0

Bind address for the gateway server.

---

**`server.port`** `int` — default: 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`** `bool` — default: 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`** `int` — default: 300

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

---

**`session.max_sessions_per_service`** `int` — default: 100

Maximum concurrent sessions per MCP service.

---

**`session.cleanup_interval`** `int` — default: 60

Interval in seconds between session cleanup sweeps.

---

### rate\_limiting

**`rate_limiting.default_limits`** `list[str]` — default: \["200 per day", "50 per hour"]

Default rate limits applied to all endpoints.

---

**`rate_limiting.tools_limit`** `string` — default: 30 per minute

Rate limit for the tool listing endpoint.

---

**`rate_limiting.call_limit`** `string` — default: 10 per minute

Rate limit for tool call endpoints.

---

**`rate_limiting.session_delete_limit`** `string` — default: 20 per minute

Rate limit for session deletion endpoints.

---

**`rate_limiting.storage_uri`** `string` — default: 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

```bash
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`][securityconfig]
for security headers (X-Content-Type-Options, X-Frame-Options, HSTS, etc.).

## Example

```bash
# Start with default config.json
mcp-gateway

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