> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.itential.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server. # MCP server configuration reference > Reference information for MCP server configuration fields, transport types, secret template syntax, and database export behavior in Itential Gateway. 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](./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](#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: ```bash --env API_KEY={{ secret "my-api-key" }} ``` Reference a secret in an HTTP header: ```bash --header Authorization=Bearer {{ secret "my-token" }} ``` Reference a secret in the server command: ```bash 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_` 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 ``` ---