Register and manage MCP servers

Platform 6.5+ Gateway 5.5+

MCP server lifecycle management happens in Itential Gateway. When you register an MCP server, Itential Gateway establishes connectivity, discovers the tools the server exposes, and surfaces them in Gateway Manager automatically as native gateway services. Gateway Manager reflects what Itential Gateway exposes—you don’t configure tools directly in Gateway Manager.

Prerequisites

Before you register an MCP server, confirm the following:

You have operator-level access in Itential Gateway.
The MCP server endpoint URL or command is available.
Any credentials required by the MCP server are stored in Itential Gateway’s secrets management.

Register an MCP server

Registering an MCP server creates a persistent definition in Itential Gateway, establishes connectivity to the server, and triggers automatic tool discovery.

$ iagctl mcp server add <name> <command_or_url> [flags]

Replace <name> with a unique identifier for the server and <command_or_url> with either a shell command (for stdio transport) or an HTTP/HTTPS URL (for HTTP transport).

Transport auto-detection

If you omit the --transport flag, Itential Gateway detects the transport type automatically:

Arguments beginning with http use streamable-http transport.
All other arguments use stdio transport.

Available flags

Flag	Description
`--description`	A brief description of the server.
`--transport`	Transport type: `stdio`, `streamable-http`, or `sse`. Auto-detected if omitted.
`--tag`	Metadata tag to associate with the server. Repeatable.
`--env KEY=VALUE`	Environment variable for the server process. stdio transport only. Repeatable.
`--header KEY=VALUE`	Custom HTTP header. HTTP transports only. Repeatable.

Secret references

The <command_or_url> argument and the --env and --header flag values all support Go template syntax. Use {{ secret "name" }} to reference a secret stored in Itential Gateway’s secret store instead of providing sensitive values as plain text.

Example: stdio server with environment variables

$ iagctl mcp server add data-processor "python /opt/mcp/processor.py" \
>   --description "Data processing MCP server" \
>   --tag production \
>   --env DB_HOST=localhost \
>   --env DB_PASSWORD={{ secret "db-password" }}

Example: HTTP server with custom headers

$ iagctl mcp server add secure-api https://mcp.internal.example.com \
>   --transport streamable-http \
>   --description "Internal API gateway" \
>   --header Authorization=Bearer {{ secret "api-token" }}

For full CLI reference and additional examples, see iagctl mcp server add.

Remove an MCP server

To change an MCP server’s configuration, remove it and re-register it with the updated settings. Removing an MCP server deletes its definition from Itential Gateway, terminates connectivity, and withdraws all of its tools from Gateway Manager.

This action cannot be undone. Workflows or agents that rely on the server’s tools will no longer be able to invoke them. Confirm that no active workflows or agents depend on the server before removing it. To restore access, you must re-register the server using the same configuration.

To remove an MCP server:

$ iagctl mcp server remove <name>

For full CLI reference, see iagctl mcp server remove.

Inspect an MCP server

Inspecting an MCP server displays its current configuration without requiring access to the underlying infrastructure. Credentials are never returned in inspection output.

To inspect an MCP server:

$ iagctl mcp server inspect <name>

To return the configuration as JSON, add the --raw flag:

$ iagctl mcp server inspect <name> --raw

For full CLI reference, see iagctl mcp server inspect.

Verify your setup

After registering an MCP server, confirm the following:

The server appears in the registered MCP servers list in Itential Gateway.
The server’s tools are visible in Gateway Manager as gateway services.
RBAC permissions are applied to the MCP-backed services as expected. MCP-backed gateway services inherit the same Gateway Manager permission model as all other gateway services—no additional permission configuration is required.

To list the tools discovered from a registered server using the CLI:

$ iagctl mcp tool list <name>

Use the --raw flag to return full tool schema information, including input and output parameters:

$ iagctl mcp tool list <name> --raw