MCP server configuration reference

Platform 6.5+ Gateway 5.5+

This page is a reference for MCP server configuration in Itential Gateway. It covers the fields used when registering an MCP server, supported transport types, secret template syntax, and database export behavior.

For step-by-step procedures, see Register and manage MCP servers.

Configuration fields

These fields define an MCP server registration.

Field	Type	Required	Description
`name`	String	Yes	Unique identifier for the MCP server within Itential Gateway. Used to reference the server in CLI commands and Gateway Manager.
`command_or_url`	String	Yes	Either a shell command to launch a stdio subprocess (for example, `python /opt/mcp/server.py`) or an HTTP/HTTPS URL (for example, `https://mcp.example.com`). Supports Go template syntax.
`transport`	String	Yes	Transport type. Auto-detected from `command_or_url` if omitted. Valid values: `stdio`, `streamable-http`, `sse`. See Transport types.
`description`	String	No	Freeform text description of the server’s purpose.
`tags`	Array of strings	No	One or more string labels for organizing and filtering servers.
`env`	Array of key=value pairs	No	Environment variables to pass to the server subprocess. `stdio` transport only. Supports Go template syntax, including `{{ secret "name" }}` references.
`headers`	Array of key=value pairs	No	Custom HTTP headers to send with requests to the server. HTTP transports only. Supports Go template syntax, including `{{ secret "name" }}` references.

Credentials are stored via Itential Gateway’s secrets manager and are never returned in plaintext. Inspection and export output redacts all secret values.

Transport types

Itential Gateway supports three transport types for MCP server communication.

Transport	Value	Use when
Standard I/O	`stdio`	The MCP server runs as a local subprocess launched by a shell command.
Streamable HTTP	`streamable-http`	The MCP server is accessible at an HTTP or HTTPS endpoint.
Server-Sent Events	`sse`	The MCP server uses SSE transport. Supported but not commonly used.

Auto-detection behavior

If you omit --transport when using the CLI, or don’t specify a transport in the Gateway UI, Itential Gateway detects the transport automatically:

command_or_url values beginning with http → streamable-http
All other values → stdio

Specify --transport explicitly when auto-detection would produce the wrong result.

Transport and field compatibility

Field	`stdio`	`streamable-http`	`sse`
`env`	✓	—	—
`headers`	—	✓	✓

Secret template syntax

The command_or_url field and env and header values support Go template syntax. Use the secret function to reference a secret stored in Itential Gateway’s secret store instead of providing sensitive values as plain text.

Syntax

{{ secret "secret-name" }}

Replace secret-name with the name of the secret as stored in Itential Gateway’s secrets management.

Examples

Reference a secret in an environment variable:

$ --env API_KEY={{ secret "my-api-key" }}

Reference a secret in an HTTP header:

$ --header Authorization=Bearer {{ secret "my-token" }}

Reference a secret in the server command:

$ iagctl mcp server add my-server "npx @mcp-server/{{ .serverType }}"

Feature flag

FlowMCP Gateway functionality is controlled by the mcp_enabled feature flag, which defaults to true. MCP commands and endpoints are available without any additional configuration unless the flag has been explicitly disabled.

Configuration method	Setting
Gateway configuration file	Set `mcp_enabled = false` in the `[features]` section to disable
Environment variable	Set `GATEWAY_FEATURES_MCP_ENABLED=false` to disable

Database export and import behavior

MCP server configurations are included in Itential Gateway database exports by default. When you import a database into a new Itential Gateway instance, MCP server definitions are restored.

Any credentials required by an MCP server’s transport configuration are handled through Itential Gateway’s secrets-reference model rather than being included as plaintext values. Exported configurations reference credentials using a $GATEWAYSECRET_<alias> value, which Itential Gateway resolves at runtime against the target instance’s stored secrets. Confirm that the corresponding secrets exist on the destination instance before importing, since the import doesn’t create or transfer the underlying secret values themselves.

Gateway service representation

When Itential Gateway discovers the tools exposed by a registered MCP server, it surfaces them in Gateway Manager as native gateway services. MCP-backed gateway services behave the same as all other gateway services:

They’re subject to the same Gateway Manager RBAC permission model.
They’re available to Platform workflows and agents through the same tool attachment mechanism.
They participate in agent project tool discovery.

Each registered MCP server is represented internally as an McpServer object with the following fields: id, name, created, and transport configuration. Each tool it exposes is represented as an McpTool object with the following fields: name, description, input_schema, and output_schema.

JSON-RPC methods

Itential Gateway exposes the following JSON-RPC types for MCP server management and tool invocation.

McpListToolsRequest

Lists the tools available on a registered MCP server.

Field	Description
`server`	The name of the registered MCP server.

McpCallToolRequest

Invokes a tool on a registered MCP server.

Field	Description
`name`	The name of the tool to invoke.
`server`	The name of the registered MCP server.
`params`	The tool input arguments as a JSON string.

McpCallToolResponse

The response returned after a tool invocation.

Field	Description
`response`	The tool output as a text string.
`return_code`	The return code from the tool invocation.
`json`	The tool output as a structured JSON value, when available.

Error handling

No errors are reported during server registration. Errors are returned in the following situations:

Accessing an MCP server that isn’t registered returns a NotFound error.
Calling a tool on an unavailable MCP server returns an Internal error.
Calling a tool with invalid parameters returns an Internal error containing an MCP-level validation message.

Example errors

Error: rpc error: code = NotFound desc = mcp server not found

Error: rpc error: code = Internal desc = tool call failed: MCP error -32602: Input validation error: Invalid arguments