MCP Server

The iris-mcp-server configuration file accepts several formats for credential fields:

• Literal — A string, such as "CSPSystem".

• Environment variable — A string in the form "@{env:CRED}", where CRED is an environment variable.

• Vault KV2 — A string in the form "@{vault:path/#field}", where path/ is the path relative to the vault_mountOpens in a new tab and field is the Vault field.

  This option is only available for HashiCorp Vault users and requires you to enable the vault feature in your configuration file. For details, see HashiCorp Vault Integration.

As a best practice, you should prefer using either environment variables or references to HashiCorp Vault credentials over using literals.

The stdio transport mode communicates with a local MCP client through standard I/O.

The following example configures iris-mcp-server to use stdio. It also includes a section for logging directly to a file because the default logging output mode, stderr, is not compatible with stdio:

[mcp]
transport = "stdio"

[logging]
output = "file"
file   = "C:\\logs\\iris-mcp.log"

The http transport mode communicates with a remote MCP client through HTTP. This is an unencrypted connection, so you should only use it if your network is secured in some other way.

The following example configures iris-mcp-server to use http:

[mcp]
transport = "http"
host      = "127.0.0.1"
port      = 8080

The https transport mode communicates with a remote MCP client through HTTPS, such as ChatGPT. This transport mode encrypts the connection with TLS, so you need to provide a server TLS certificate and key in PEM format:

The following example configures iris-mcp-server to use https:

[mcp]
transport = "https"
host      = "127.0.0.1"
port      = 8443

[mcp.tls]
cert = "/etc/certs/server.crt"
key  = "/etc/certs/server.key"

Alternatively, if you use HashiCorp Vault and have enabled vault integration, then you specify the cert and key from your Vault:

[mcp.tls]
cert = "@{vault:tls/iris-mcp#certificate}"
key  = "@{vault:tls/iris-mcp#private_key}"

When using http or https transport and binding to 0.0.0.0, you can configure iris-mcp-server to validate the Host header on incoming requests to prevent DNS rebinding attacks.

To validate incoming requests, you can provide a list of allowed hosts in mcp.allowed_hosts:

[mcp]
transport     = "http"
host          = "0.0.0.0"
port          = 8080
allowed_hosts = ["mcp.example.com", "mcp.example.com:8080", "[2001:db8::1]:8443"]

This can be useful in cases where for example, your InterSystems IRIS instance and iris-mcp-server are in a container in AWS and are behind a load balancer hosted on mcp.example.com. MCP clients would therefore send requests to mcp.example.com, which would then forward those requests to iris-mcp-server. If you set allowed_hosts, it will validate that the requests are coming from the hosts you expect (the load balancer, mcp.example.com, in this case).

You can also specifically allow or deny particular networks by IP address. If the same IP address is specified in both lists, it is denied:

# Peer IP allow/deny lists, in CIDR notation (optional, IPv4 and IPv6 may be
# mixed freely). Enforced at TCP-accept time, before any HTTP/TLS handshake.
# Empty allowed_networks (the default) means all peers are allowed, subject
# to denied_networks; denied_networks always takes precedence.
# allowed_networks = ["10.0.0.0/8", "2001:db8::/32"]
# denied_networks  = ["10.0.5.0/24"]

Each pooled session corresponds to one InterSystems IRIS license slot (job). Three settings control how long sessions live:

• idle_timeout — (Default: "5m") How long, a session can be idle before it is closed, which halts the InterSystems IRIS job and frees its license. This parameter is a string and accepts values with units such as "70ms" (70 milliseconds), "1m" (one minute), "2h" (two hours), and so on.

  For OAuth sessions, InterSystems IRIS validates a Bearer token once when the WebSocket session is opened. It does not re-validate the token while the session is running; a session stays alive even after the token expires. idle_timeout is therefore the primary mechanism for cleaning up stale-token sessions; you should set idle_timeout to a value less than or equal to your OAuth token lifetime so that expired sessions are recycled before the next token rotation.

• max_sessions_per_auth_context — (Default: pool.max) The maximum number of sessions per token identity (OAuth or otherwise).

• max_age — (Default: None; only idle_timeout applies) The maximum length of a session. If a session's length exceeds this, it is closed the next time it's idle. This parameter is a string and accepts values with units such as "70ms" (70 miliseconds), "1m" (one minute), "2h" (two hours), and so on.

In deployments with many OAuth users (each user gets their own session pool), lower idle_timeout and set max_sessions_per_auth_context to prevent license exhaustion:

[[iris]]
name                          = "production"
server                        = { host = "iris.example.com", port = 1972, username = "CSPSystem", password = "SYS" }
pool                          = { min = 2, max = 10 }
idle_timeout                  = "5m"   # free licenses after 5 minutes idle
max_sessions_per_auth_context = 3    # each user may have at most 3 concurrent sessions
max_age                       = "1h"  # recycle sessions after 1 hour regardless of activity
endpoints                     = [{ path = "/mcp/prod" }]

In deployments with multiple InterSystems IRIS instances, each instance gets its own pool:

[[iris]]
name   = "primary"
server = { host = "iris1.example.com", port = 1972, username = "CSPSystem", password = "SYS" }
pool   = { min = 5, max = 20 }
endpoints = [{ path = "/mcp/prod" }]

[[iris]]
name   = "analytics"
server = { host = "iris2.example.com", port = 1972, username = "CSPSystem", password = "SYS" }
pool   = { min = 2, max = 10 }
endpoints = [{ path = "/mcp/analytics" }]

To authenticate to InterSystems IRIS with the iris-mcp-server, provide the credentials of a privileged gateway user (such as CSPSystemOpens in a new tab) in the server inline table:

server = { host = "iris.example.com", port = 1972, username = "CSPSystem", password = "SYS" }

To authenticate to an MCP server endpoint with the iris-mcp-server, provide the credentials in the endpoints array, where each entry consists of an inline table of a path and credentials. The following example shows how to provide credentials depending on their Allowed Authentication Methods:

endpoints = [
  # Unauthenticated (should only be used with stdio, if at all) or OAuth2.
  # For OAuth2, the credentials are provided to your authorization server and the token is used to validate
  # to the resource server (the resource being the MCP server endpoint); it is not stored in the configuration file.
  { path = "/mcp/myservice" },

  # Password or LDAP
  { path = "/mcp/myotherservice", username = "myUser", password = "myPassword" },
]

You can encrypt the superserver-side connection between iris-mcp-server and InterSystems IRIS by adding the tls field to the [[iris]] entry of your configuration file. The presence of the tls field enables TLS and its value determines which certificates and keys to use for the connection:

• tls = {} — Use the system's default CA certificates to verify the identity of the InterSystems IRIS server.

• tls = { ca_cert = path/to/ca.crt } - Use the CA certificate ca.crt to verify the identity of the InterSystems IRIS server.

• tls = { ca_cert = path/to/ca.crt, cert = path/to/client.crt, key = /path/to/client.key } — (Mutual TLS only) Use the CA certificate ca.crt to verify the identity of the InterSystems IRIS server and present the certificate client.crt to InterSystems IRIS.

If you've integrated iris-mcp-server with HashiCorp Vault, you can reference your secrets instead:

tls = { ca_cert = "@{vault:tls/iris#ca_cert}" }

You can encrypt the connection between LLM clients and iris-mcp-server the MCP server endpoints by adding the cert and key fields to [mcp.tls]:

# Both from files
[mcp.tls]
cert = "/etc/certs/server.crt"
key  = "/etc/certs/server.key"

# HashiCorp Vault integration
[mcp.tls]
cert = "@{vault:tls/iris-mcp#certificate}"
key  = "@{vault:tls/iris-mcp#private_key}"

iris-mcp-server supports RAG-based (Retrieval-Augmented Generation) smart tool discovery, to perform a semantic search across all registered tool descriptions. When an LLM asks for tools with a natural-language query, the relevant tools are returned automatically.

To enable this feature in your configuration file:

[features]
smart_discovery = true

The background tool-refresh loop fetches tool lists in the interval defined by tool_refresh_interval (default: "5m"). This parameter is a string and accepts values with units such as "70ms" (70 milliseconds), "1m" (one minute), "2h" (two hours), and so on.

A 304 Not Modified response means no change and tools are not reregistered. On a 200 response, iris-mcp-server only reregisters and sends notifications to MCP clients for tools that have changed.

The following example shows how to configure tool_refresh_interval:

[[iris]]
name                       = "dev"
server                     = { host = "localhost", port = 1972, username = "CSPSystem", password = "SYS" }
pool                       = { min = 2, max = 5 }
tool_refresh_interval      = "1m"    # poll every minute
endpoints                  = [{ path = "/mcp/myapp" }]

If don't specify any MCP server endpoints in [[iris]], iris-mcp-server queries the InterSystems IRIS CSP application registry for all applications whose names start with /mcp and connects to each one automatically.

[[iris]]
name   = "local"
server = { host = "localhost", port = 1972, username = "CSPSystem", password = "SYS" }
pool   = { min = 2, max = 5 }
# endpoints omitted, so auto-discover /mcp* apps

When iris-mcp-server is connected to an MCP server endpoint, the tools provided by that endpoint are prefixed with a service ID derived from the MCP server's path. These prefixes prevent name collisions and tell the LLM which service each tool belongs to.

The service ID is the endpoint path of the MCP Server with the leading slash stripped and remaining slashes replaced with underscores. For example:

If iris-mcp-server loses its connection to InterSystems IRIS, iris-mcp-server automatically attempts to reconnect in the background in the interval defined by reconnect_interval (default: "30s"). You do not need to restart iris-mcp-server.

This parameter is a string and accepts values with units such as "70ms" (70 milliseconds), "1m" (one minute), "2h" (two hours), and so on.

The example below configures iris-mcp-server to attempt to reconnect every 10 seconds:

[[iris]]
name                    = "dev"
server                  = { host = "localhost", port = 1972, username = "CSPSystem", password = "SYS" }
pool                    = { min = 2, max = 5 }
reconnect_interval      = "10s"     # attempt to reconnect every 10 seconds
endpoints               = [{ path = "/mcp/myapp" }]

iris-mcp-server includes a live terminal dashboard that shows connection pool status, active sessions, tool call throughput, and a live log feed. These are updated every 500 milliseconds.

To use this monitoring tool:

1. Start iris-mcp-server. This outputs the IPC socket path in the form /tmp/iris-mcp-PID.sock:

   ./iris-mcp-server run
   ...
   2026-06-05 20:20:56.521  INFO IPC server listening on /tmp/iris-mcp-15108.sock (mode 0600, owner-only)
   2026-06-05 20:20:56.522  INFO IPC metrics socket: /tmp/iris-mcp-15108.sock  (iris-mcp-server monitor --socket /tmp/iris-mcp-15108.sock)
   ...
   

   

2. Start the monitoring tool, specifying either the socket path or PID to connect to the iris-mcp-server:

   Linux:

   # Unix, connect by PID
   iris-mcp-server monitor --pid 15108
   
   # Unix, connect by explicit socket path
   iris-mcp-server monitor --socket /run/user/1000/iris-mcp-15108.sock
   

   

   Windows:

   # Windows, connect by PID
   iris-mcp-server.exe monitor --pid 15108
   
   # Windows, connect by explicit socket path
   iris-mcp-server.exe monitor --socket \\.\pipe\iris-mcp-15108
   

   

3. To exit the monitoring tool, press q. This does not interrupt the iris-mcp-server process.

The monitoring tool provides the following dashboard panels:

• GATEWAY — Active MCP sessions, authenticated contexts (distinct OAuth identities), WebSocket sessions, error counts, and discovery cache hit rates

• CONNECTIONS — Per-endpoint WebSocket pool state (active, queued, idle, total), P50/P99 latency per tool, session eviction counts by reason, InterSystems IRIS connection failure breakdown by reason, HTTP pool self-heal counters (stale/healed/failed), and WebSocket session error breakdown (send, receive, stale-session)

• TOOLS — Per-tool call counts, success/error rates, P50/P99 execution latency, and input/output byte totals

• LOG — Live stream of recent INFO/WARN/ERROR log lines, color-coded by severity

The monitoring tool communicates with the iris-mcp-server through a local IPC channel (a named pipe on Windows and a Unix domain socket on Unix). The channel is strictly one-way; the monitor receives periodic read-only metrics and cannot send commands to the server. This local IPC channel also cannot be accessed over the network.

• Windows — Access to the monitoring tool is restricted to the user who started iris-mcp-server, the SYSTEM account, and members of the local Administrators group. No other local user account can connect to the monitor.

• Unix — The socket file is created with mode 0600. Only the user who started iris-mcp-server and root can connect to the monitor.

iris-mcp-server has robust logging capabilities. It collects and outputs the following information:

• Connection events (connect, disconnect, reconnect)

• Tool discovery requests and ETag comparisons

• STP request/response JSON

• Smart discovery indexing

Logging is configured by specifying, in the [logging section of the configuration file, a log level and an output location.

The log level expresses the minimum level of severity that you want to record. This means that if you set the log level to info, the log will contain messages of severity info and above, which includes info, warn, and error. These are ordered by the most to least severe:

1. error (most severe)

2. warn

3. info (default)

4. debug

The output location expresses where the logs should be written:

• stderr (default) — Logs are written to stderr. This logging method is incompatible with the stdio transport mode.

• output — Logs are written to the file specified by logging.file.

• file — (Required only if output = "file"; ignored otherwise) A file path to write logs to.

The following examples show how to set these options with CLI flags and a configuration file.

To write logs of severity debug and higher to stderr:

iris-mcp-server --log-level debug --log-output stderr --config config.toml run

To write logs of severity debug and higher to /example/iris-mcp.log:

[logging]
level  = "debug"
output = "file"
file   = "/example/iris-mcp.log"

To enable OpenTelemetry tracing:

1. Enable the telemetry feature in your configuration file:

2. Set up the OpenTelemetry Protocol (OTLP) endpoint with the OTEL_EXPORTER_OTLP_ENDPOINT environment variable.

   export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317"
   

   

3. Run Jaeger for local trace visualization:

   docker run -d --name jaeger \
     -p 16686:16686 \
     -p 4317:4317 \
     jaegertracing/all-in-one:latest
   # View traces at http://localhost:16686
   

   

If you use the --status-tool flag, iris-mcp-server exposes a special MCP tool called iris_status that the LLM can call to report connection errors or startup failures. This tool only appears in the tool list when there are active errors.

If the LLM sees that the iris_status tool is available, it means that something went wrong. Calling it returns a structured report of all current errors:

iris_status result:
- mcp_database: connection failed — refused at localhost:1972
- mcp_analytics: authentication error — 403 Forbidden (check endpoint credentials)

This allows the LLM to proactively report issues rather than silently failing when tools are called.

1. Verify that the InterSystems IRIS superserver is running on the configured port.

2. Verify that the MCP server endpoint in InterSystems IRIS (System Administration > Security > Applications > MCP Servers) exists and is enabled.

3. Verify that the Dispatch Class is set in the MCP server endpoint and that the class is compiled in InterSystems IRIS.

4. Verify that the credentials specified for server.username and server.password in [[iris]] are correct. These are gateway-level credentials for a privileged gateway user (for example, CSPSystem), not InterSystems IRIS application user credentials.

5. Verify that your firewall allows TCP connections to the InterSystems IRIS superserver port.

The Tool call error: 403 Forbidden error means that you successfully authenticated with InterSystems IRIS, but not with the MCP server endpoint.

1. Verify that the MCP server endpoint entry in [[iris]] has the correct credentials (username and password or bearer).

2. For HTTP Basic authentication: verify that the username and password are valid InterSystems IRIS credentials for a user with the required resource for that endpoint.

3. OAuth passthrough: Verify that the MCP client is sending a valid Authorization header with its requests.

4. Verify that the MCP server's Allowed Authentication Methods are what you expect.

iris-mcp-server establishes the connection between your LLM and InterSystems IRIS, but you do not see any tools (or your LLM only sees the special iris_status tool).

First, verify whether the issue is on the InterSystems IRIS side or the LLM side:

• View the output of iris_status to see if it reported the source of the error. If it does not report any issues, then the error is on the InterSystems IRIS side.

• Run iris-mcp-server with the log level set to debug and look for the tool count logged during discovery. If this shows 0 tools, then the issue is on the InterSystems IRIS side.

If the issue is on the InterSystems IRIS side, then your tools aren't appearing because of a misconfigured MCP server:

1. Verify that the SPECIFICATION parameter of the MCP service class is not empty and references the correct class names.

2. Verify that all listed tool/toolset classes are compiled in the correct namespace.

3. Verify that the Namespace setting of all MCP servers match where the service classes are compiled.

To confirm whether iris-mcp-server is discovering tools, verify that the startup logs contain entries in the form:

registered N tools from /mcp/database

Where N refers is the number of tools registered. If no tools are registered, set the logging level to debug and look for discovery errors.

If you have access to an InterSystems IRIS web gateway (not the superserver port), you can also send a request to the InterSystems IRIS health endpoint directly:

curl http://iris-web-gateway-host/mcp/database/v1/health

If a tool appears in discovery but the tool call fails or if a particular tool is not shown that particular tool might be misconfigured:

1. Verify that the SPECIFICATION parameter of the MCP service class includes the tool or toolset.

2. Verify that the method is public (that is, not set as Private or Internal).

3. Tool names are case-sensitive; verify the names logged during discovery by setting the log level to debug.

If your iris-mcp-server exits at startup with a secret resolution error:

1. For environment variables (@{env:VAR}), verify that the environment variable is set.

2. For vault secrets (@{vault:path#field}), verify that the Vault specified by your configuration file is accessible. This includes:

   • Verify that vault_addr is reachable.

   • Verify that vault_token is valid.

   • Verify that you have permission for the specified secret: vault token lookupOpens in a new tab

   • Verify that the path in the secret reference exists.

   • Verify that the field in the secret reference exactly matches the one in the Vault.