Skip to navigation

McpGatewaySkill

View as MarkdownOpen in Claude

Bridge a Model Context Protocol (MCP) Gateway service with SWAIG functions. The skill connects to the gateway at load time, enumerates the configured services and tools, and registers each as a SWAIG function on the agent.

The gateway URL is validated by an SSRF guard — private, loopback, and cloud-metadata endpoints are rejected. Every later request, and every redirect it follows, is checked the same way, so a gateway that redirects to a private or internal address, or a hostname that later resolves to one, is refused. A tool call is tried up to retry_attempts times in total, with a per-request timeout of request_timeout seconds. It’s tried again after a connection error, a timeout, a refused address, or an HTTP 5xx response, but not after a 4xx response or a 200 whose body isn’t JSON.

Class: McpGatewaySkill

Tools: Dynamically registered from the gateway (prefixed by tool_prefix)

Env vars: MCP_GATEWAY_AUTH_TOKEN, MCP_GATEWAY_AUTH_USER, MCP_GATEWAY_AUTH_PASSWORD

gateway_url
stringRequired

URL of the MCP Gateway service. Must pass the SSRF guard.

auth_token
string

Bearer token for authentication. Falls back to the MCP_GATEWAY_AUTH_TOKEN environment variable. Takes precedence over basic auth when provided.

auth_user
string

Basic-auth username (used when auth_token is not supplied). Falls back to MCP_GATEWAY_AUTH_USER.

auth_password
string

Basic-auth password. Falls back to MCP_GATEWAY_AUTH_PASSWORD.

services
McpServiceConfig[]Defaults to []

Services to expose. Each entry has:

  • name (string) — service name registered on the gateway.
  • tools ("*" or string[]) — which tools to expose from that service.

Empty array exposes every available service/tool.

session_timeout
integerDefaults to 300

Gateway session timeout in seconds.

tool_prefix
stringDefaults to mcp_

Prefix prepended to each SWAIG function name registered from the gateway (e.g., mcp_todo_add_todo).

retry_attempts
integerDefaults to 3

Total attempts per tool call, including the first.

request_timeout
integerDefaults to 30

Per-request timeout in seconds.

verify_ssl
booleanDefaults to true

Whether to verify TLS certificates on outbound requests. Setting this to false alone is ignored; verification stays on unless allow_insecure_tls is also true.

allow_insecure_tls
booleanDefaults to false

Explicit opt-in that, together with verify_ssl: false, disables TLS certificate verification. Only the certificate check is skipped: the address checks still apply.

Disabling TLS verification accepts any certificate

With verify_ssl: false and allow_insecure_tls: true, outbound requests to the gateway accept any certificate and are exposed to interception. Use it only against a trusted self-signed gateway on a private network.

Example

import { AgentBase, McpGatewaySkill } from '@signalwire/sdk';
const agent = new AgentBase({ name: 'assistant', route: '/assistant' });
agent.setPromptText('You are a helpful assistant.');
await agent.addSkill(new McpGatewaySkill({
gateway_url: 'https://mcp.internal.example.com',
services: [
{ name: 'search', tools: '*' },
{ name: 'calendar', tools: ['list_events', 'create_event'] },
],
tool_prefix: 'mcp_',
}));
agent.run();