Skip to main content

MCP Server

The Model Context Protocol (MCP) is a method for giving LLMs access to external systems and data. In the context of InterSystems IRIS, the MCP lets you expose tools and data in your InterSystems IRIS instance to your preferred models. Implementing this protocol is the iris-mcp-server binary, an MCP gateway that bridges LLM clients to InterSystems IRIS MCP server endpoints. These endpoints provide the tools to your agent.

Note:

In the InterSystems IRIS 2026.3 release, AI Hub functionality is only available from an AI Hub-enabled kitOpens in a new tab or container image. You can upgrade from a standard InterSystems IRIS installation to a kit with InterSystems IRIS AI Hub as normal for Continuous Delivery releases, but you cannot "downgrade" to a regular, non-AI Hub InterSystems IRIS installation afterwards.

InterSystems IRIS installations with AI Hub cannot be "downgraded" back to a standard, non-AI Hub InterSystems IRIS installation.

Features marked with * (asterisk) are experimental and its APIs may change in a future release.

For additional examples, see the Samples-AIHubOpens in a new tab repository.

Quickstart - Local MCP (stdio)

The following procedure shows how to set up a connection between an MCP client (in this case, Claude Desktop, but any client that implements the MCP will work) and an MCP endpoint that exposes an ObjectScript method as a tool.

Connections between an MCP client and an InterSystems IRIS MCP endpoint are mediated by the iris-mcp-server binary included with your InterSystems IRIS installation:

  1. Create a %AI.Tool or %AI.ToolSet:

    Class Sample.GetServerTime Extends %AI.Tool
    {
    
    Property Name As %String [ InitialExpression = "GetServerTime" ];
    
    Property Description As %String(MAXLEN = "") [ InitialExpression = "Gets the current system time." ];
    
    /// Get the current server time.
    ClassMethod GetServerTime() As %String
    {
        Return $ZTIME($PIECE($HOROLOG,",",2),1)
    }
    
    }

    For more information about tools, see AI Hub ObjectScript SDK.

  2. Create an MCP service class, specifying the tool you just defined. This allows your MCP client to use these tools when responding to requests.

    1. In the Management Portal, go to System Administration > Security > Applications > MCP Servers.

    2. Select Create New MCP Server.

  3. Create an MCP service class, specifying the name of your tool:

    Class MyApp.MCP.MyService Extends %AI.MCP.Service
    {
      // Comma-delimited string of %AI.Tool or %AI.ToolSet names,
      // for example: "My.Tool,My.OtherTool,My.ToolSet"
        Parameter SPECIFICATION As STRING = "Sample.GetServerTime";
    }
    
  4. Add an MCP server to your InterSystems IRIS and specify your service class:

    1. In the Management Portal, go to System Administration > Security > Applications > MCP Servers.

    2. Select Create New MCP server*, specifying the following:

      • Name — /mcp/myservice

      • Namespace — USER

      • Dispatch Class — MyApp.MCP.MyService

      • Enable Service — Select this option.

      • Allowed Authentication Methods — Password. Because this example is using the stdio (specified in the next step) transport mode, all communication to the MCP endpoint is local, so you can instead select Unauthenticated, but you should not use Unauthenticated in a production environment.

        For details on authenticating MCP endpoints, see MCP Server Endpoint Authentication.

  5. Configure iris-mcp-server to point to your InterSystems IRIS instance and its MCP server. The example below contains the contents of config.toml, a configuration file that specifies the InterSystems IRIS instance with server and the MCP endpoint with endpoints:

    # Connection method and information for the connection between
    # your MCP client and iris-mcp-server (which acts as a bridge between your client
    # and the MCP endpoint exposed by InterSystems IRIS)
    [mcp]
    transport = "stdio"
    
    [[iris]]
    # Arbitrary name for this block of InterSystems IRIS connection information
    name   = "local"
    
    # Server connection information: the host, superserver port, and the user that
    # iris-mcp-server (not the MCP client) should authenticate as
    server = { host = "localhost", port = 1972, username = "CSPSystem", password = "SYS" }
    
    # Connection pool
    pool   = { min = 2, max = 5 }
    
    # The MCP endpoints in InterSystems IRIS
    # The credentials specified for this endpoint determine what user
    # that the MCP client will authenticate as.
    endpoints = [
      { path = "/mcp/myservice", username = "superuser", password = "SYS" },
    ]
    
    [logging]
    level  = "info"
    output = "file"
    file   = "C:/InterSystems/iris-mcp.log"
    
  6. Start iris-mcp-server. This example uses the stdio transport mode, so you should configure your MCP client to start iris-mcp-server on its own. For Claude Desktop, add the following to claude_desktop_config.json:

    "mcpServers": {
      "iris-stdio": {
        "command": "C:\\InterSystems\\IRIS\\bin\\iris-mcp-server.exe",
        "args": [
          "--config=C:\\InterSystems\\IRIS\\bin\\config.toml",
          "run"
        ]
      }
    }
    
  7. Restart your MCP client and try to ask it a question that requires the use of one of the tools that you defined. Your MCP client might prompt you to allow the use of the tool before answering your question.

    In this example, Claude Desktop uses the user-defined GetServerTime tool to get the time on the current instance:

    What's the current server time?
    
    The current InterSystems IRIS instance time is 1:35:56 PM.
    

Configuring Remote MCP (HTTP)

The quickstart example configures an MCP client to communicate with a local iris-mcp-server. To connect your MCP client with a remote iris-mcp-server, you should instead use the http or https transport modes.

This particular example covers http. For details on how to configure https, see Using TLS.

  1. For http, add the following in your iris-mcp-server configuration file:

    [mcp]
    # iris-mcp-server binds to 192.0.2.0 on port 38991
    # Reachable by the client at http://192.0.2.0:38991/mcp
    transport = "http"
    host = "192.0.2.0"
    port = 38991
    
  2. Start iris-mcp-server, specifying the configuration file:

    iris-mcp-server --config /path/to/config.toml run
    
  3. Configure your MCP client to connect to the host and port that you specified. For example, for Claude Desktop using mcp-remote:

      "mcpServers": {
        "iris-http": {
          "command": "npx",
          "args": [
            "-y",
            "mcp-remote",
            "http://192.0.2.0:38991/mcp"
          ]
        }
    }
    

MCP Editor*

The MCP Editor is an experimental Management Portal interface for composing existing tools, toolsets, and queries to make new toolsets and then using those toolsets to create an MCP service. To view it, on the MCP Servers page (System Administration > Security > Applications > MCP Servers), select either Create New MCP Server or an existing MCP server and then select open toolset definition wizard.

The general flow for using this interface is as follows:

  1. In General, give your toolset a name and description. You can also choose to expose it as an MCP server endpoint.

  2. In Custom Tools or Toolsets tabs, define your toolset or MCP server endpoint as a composition of existing tools and custom inline queries.

  3. Select Save to save your toolset or MCP server endpoint.

In the General tab, you can give your toolset a name and description, and expose it as an MCP server:

  • Toolset Name — The name of the toolset.

  • Toolset Class — The name of the %AI.ToolSet class.

  • Description — An optional description.

  • Expose as MCP Server — Whether to use the toolset for a service class and expose it as an MCP server endpoint. Selecting this option creates both a %AI.ToolSet and %AI.MCP.Service subclass and uses it to create a new MCP server and also enables the ToolSet tab. Use this to define which roles or resources (if any) are required to access the endpoint.

    For example, if your Toolset Name is SampleToolSet:

    • Toolset subclass — SampleToolSet.ToolSet

    • MCP service subclass — SampleToolSet.MCPService

    If you choose not to expose the toolset as an MCP server, selecting Save (only available after you add tools in the Custom Tools or Toolsets tabs) will instead only generate the toolset subclass.

In the Toolsets tab, you can associate this MCP server endpoint with existing toolset. This tab is only available if you select Expose as MCP Server. Add Toolset lets you select one or more toolsets to associate with this MCP server endpoint. If you need more granularity than that, use Custom Tools.

Note:

In the current version of the MCP Editor, associating a toolset through the Toolsets tab alone is not enough to save it as an MCP endpoint; you must also use the Custotm Tools tab to add tools. If don't want to create new tools or a new toolset, you can use the Custom Tools tab, select an existing toolset, and Copy its tools.

Alternatively, you can also create a service class manually, specifying the tools in the SPECIFICATION class parameter as a comma-delimited string of toolset names. For example:

Class MySample.MCPService Extends %AI.MCP.Service
{
Parameter SPECIFICATION As STRING = "SampleToolSet.ToolSet,OtherSampleToolSet.ToolSet";
}

In the Custom Tools tab, you can create a custom toolset using a combination of existing tools. You can also use this interface to define new inline queries:

  • Import Tools From... lets you define your new toolset as a composition of tools in existing classes.

    • Copy from Existing MCP Toolset — Imports tools from an existing %AI.ToolSet.

    • Import from Existing Tool Class — Imports tools from an existing %AI.Tool.

    After you select a tool or toolset to import, you can use Copy (for toolsets) or Discover Tools (for tools) to get a list of tools to import. You can also provide a pattern to Filter Mask to filter for tools that match the pattern, which can be useful if you have an especially long list of tools.

  • Add Custom Query lets you create a new SQL query as a tool:

    • Query Name — The name of the query.

    • Description — A description of what the query does. This can be useful for giving the agent additional context about the query, such as when it should be called, what its parameters mean, or how the data is formatted.

    • SQL Query — The SQL query with optional parameters. To add a parameter, select Add Parameter and specify its name and type.

      For example, if your query getCustomer is:

      SELECT ID, Name
      FROM Sample.Person
      WHERE ID = :customerId
      

      Then your parameter name would be customerId with type integer. This results in the inline query:

      XData Definition [ MimeType = application/xml ]
      {
      <ToolSet Name="ToolSet">
        <Query Name="getCustomer" Arguments="customerId As %Integer">
          SELECT ID, Name
      FROM Sample.Person
      WHERE ID = :customerId
        </Query>
      </ToolSet>
      }
      

Configuring iris-mcp-server

The behavior and features of iris-mcp-server are determined by a combination of CLI flags, a config.toml, and its default settings. When the same value is specified in multiple locations, the setting with the highest priority applies:

  1. CLI flag (highest)

  2. config.toml

  3. Default settings (lowest)

Credential Fields

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.

Configuration File Reference

# ── MCP Transport ─────────────────────────────────────────────────────────────
[mcp]
transport  = "stdio"        # stdio | http | https
host       = "127.0.0.1"   # bind address for HTTP/HTTPS transports (default: 127.0.0.1)
                             # IPv6 literals are also accepted, e.g. "::1" or "::".
port       = 8080           # bind port
base_route = "/mcp"         # HTTP route prefix (default: /mcp)

# Allowed Host header values for inbound HTTP/HTTPS requests (optional).
# Localhost variants are always permitted. Default behaviour:
#   loopback bind (127.0.0.1): only localhost variants accepted.
#   public bind  (0.0.0.0):    bind to all interfaces (a warning is logged).
# Set to enforce a strict allowlist on a public server:
# allowed_hosts = ["mcp.example.com", "mcp.example.com:8080"]
# An IPv6 entry must be bracketed, e.g. "[2001:db8::1]:8443".

# 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"]

# Require a bearer token from remote (non-loopback) callers before falling
# back to a configured endpoint credential (default: false, i.e. required).
# Only set to true if you specifically want an anonymous remote caller to
# execute tools as the operator-configured [iris.user_auth] identity -- see
# "Remote MCP — OAuth Passthrough" below.
# allow_anonymous = false

# Maximum concurrently accepted TCP connections on this listener (HTTP/HTTPS
# only; default: 1024). Bounds file-descriptor/memory exhaustion from a
# connection flood (including Slowloris-style attacks).
# max_connections = 1024

# Maximum number of tools/call and initialize-triggered discovery requests
# this listener processes concurrently across all sessions (default: 128).
# Additional requests are rejected immediately rather than queuing, so a
# burst of concurrent requests can't drive unbounded load onto IRIS.
# max_concurrent_requests = 128

# TLS for the MCP HTTP transport (required when transport = "https")
# [mcp.tls]
# cert = "/etc/certs/server.crt"             # path to PEM certificate
# key  = "/etc/certs/server.key"             # path to PEM private key


# ── IRIS Servers ──────────────────────────────────────────────────────────────
# Use [[iris]] (double brackets) — one entry per IRIS instance.
# Multiple instances can be declared in the same file.

[[iris]]
name = "production"

# Super-server connection credentials.

server = { host = "iris.example.com", port = 52773, username = "@{env:WG_USER}", password = "@{env:WG_PASS}" }

# WebSocket session pool for this instance.
pool = { min = 2, max = 10 }

# MCP endpoint paths on this InterSystems IRIS instance.
# Each entry is a CSP web application path, with optional application-layer auth.
# Auth options per endpoint:
#   username + password  ->  HTTP Basic (Authorization: Basic ...)
#   bearer               ->  Bearer token (Authorization: Bearer ...)
#   (no auth fields)     ->  unauthenticated endpoint (do not use in production)
endpoints = [
  { path = "/mcp/myapp" },
  { path = "/mcp/secure", username = "@{env:APP_USER}", password = "@{env:APP_PASS}" },
  { path = "/mcp/api",    bearer = "@{env:token}" },
  
]

# How often to retry a lost connection (default: "30s"). Accepts "30s", "1m", "500ms" etc.
reconnect_interval = "30s"

# How often to re-fetch the tool list (default: "5m").
tool_refresh_interval = "5m"

# Maximum bytes to accumulate from InterSystems IRIS for a single tool response (default: 10 MiB).
# Increase for tools that return very large payloads; decrease if your LLM has a
# small context window and is being overwhelmed by large results.
max_response_bytes = 10485760

# Maximum time to wait for a WebSocket session to open (default: "30s").
connect_timeout = "30s"

# Maximum time to wait for a tool call to complete once the connection is
# established -- covers both the REST tool-call round trip and the WebSocket
# response wait (default: "60s"). A hung/silent backend fails and releases
# the pooled connection instead of holding it indefinitely.
request_timeout = "60s"

# How long a pooled WebSocket session may sit idle before it is closed (default: "5m").
# Closing an idle session causes the InterSystems IRIS job to Halt, freeing its license slot.
# Lower values free licenses faster; higher values reduce reconnection overhead.
idle_timeout = "5m"

# Maximum number of concurrent pooled sessions per (endpoint, auth_context) pair.
# Each OAuth user or opaque token gets its own pool up to this limit.
# Prevents runaway license consumption when many distinct identities are active.
# Default: same as pool.max.
max_sessions_per_auth_context = 10

# Hard cap on total session lifetime, regardless of activity.
# When set, a session older than this is dropped the next time it becomes idle
# (InterSystems IRIS job Halts, license freed). Off by default — only idle_timeout applies.
# Useful in high-churn environments to guarantee periodic license recycling.
# max_age = "1h"

# TLS for the connection to this instance (optional).
# Presence of the tls field enables TLS; absence means plaintext.
# tls = {}                                         # system CA roots
# tls = { ca_cert = "/etc/certs/iris-ca.crt" }    # custom CA
# tls = { ca_cert = "/etc/certs/iris-ca.crt",      # mutual TLS
#          cert    = "/etc/certs/client.crt",
#          key     = "/etc/certs/client.key" }

# ── OAuth 2.1 Authorization Server Proxy ─────────────────────────────────────
# Optional. When present, iris-mcp-server serves:
#   GET /.well-known/oauth-authorization-server  (RFC 8414 — AS metadata discovery)
#   GET /.well-known/oauth-protected-resource    (RFC 9728 — resource metadata, MCP 2025-11-25)
# and proxies OAuth flows (authorize, token, JWKS, register) to InterSystems IRIS.
# [oauth]
# iris                 = "production"                    # [[iris]] section that is the AS
# host                 = "https://mcp.example.com"       # public base URL (optional)
# well_known_path      = "/.well-known/oauth-authorization-server"  # override if non-standard
# allowed_paths        = ["/csp/sys/auth"]               # extra paths to proxy (e.g. login pages)
# metadata_cache_ttl   = "5m"                            # how long to cache AS metadata

# ── Secret Provider ──────────────────────────────────────────────────────────
[secrets]
provider = "env"            # env | vault  (default: env)

# Required only when provider = "vault":
# vault_addr       = "http://127.0.0.1:8200"
# vault_token      = "s.xxxx"                # literal token
# vault_token_file = "/var/run/vault/token"  # or path to token file
# vault_mount      = "secret"                # KV v2 mount (default: secret)

# ── Logging ──────────────────────────────────────────────────────────────────
[logging]
level  = "info"             # error | warn | info | debug
output = "stderr"           # stderr | file
# file = "/var/log/iris-mcp.log"   # required when output = "file"

# ── Optional Feature Toggles ─────────────────────────────────────────────────
[features]
smart_discovery = false     # enable RAG tool search (requires smart-discovery feature)
telemetry       = false     # enable OpenTelemetry tracing
vault           = false     # enable Vault secret provider
monitor_ipc     = true      # run the IPC metrics server `iris-mcp-server monitor` connects to
                             # (default: true); override per-invocation with --monitor-ipc/--no-monitor-ipc

CLI Flags

The following is a list of supported CLI flags and their respective effects.

iris-mcp-server flags
Flag Description and Example
--log-level level Where level is the minimum severity level of event to log, one of the following:
  1. error (most severe)

  2. warn

  3. info (default)

  4. debug

--log-output out Where out is the location where logs are written, one of the following:
  • stderr (default) — Writes logs to stderr. You should not use stderr if --transport stdio; use file instead.

  • file — Writes logs to the file specified by --log-file, which is required if --log-output file.

--log-file path The location to output the log file, where path is a file path. This option is required if you set --log-output file.
--config path Where path is the path to a TOML configuration file.
--transport mode The method with which iris-mcp-server communicates with InterSystems IRIS, where mode is one of the following:
  • stdio

  • http://host:port

  • https://host:port

--http-tls-cert path A TLS certificate in PEM format, where path is a path to the file. This option is required if you use --transport https.
--http-tls-key path A TLS key in PEM format, where path is a path to the file. This option is required if you use --transport https.
--http-base-route path The HTTP route prefix, where path is the prefix (default: /mcp).
--help Prints command information.
--version Prints version information.

The following are the CLI flags for the run subcommand:

iris-mcp-server run subcommand flags
Flag Description and Example
--status-tool boolean Whether to expose the iris_status diagnostic tool (default: true).
--iris-host host The host for the InterSystems IRIS instance, where host is a hostname or IP address.
--iris-port port The port for the InterSystems IRIS instance, where port is the superserver port.
--iris-endpoint path for each endpoint Where path is the name of an MCP server endpoint configured in InterSystems IRIS. To specify more than one endpoint, use the --iris-endpoint flag for each one. For example: --iris-endpoint /mcp/myservice --iris-endpoint /mcp/myotherservice
--monitor-ipc boolean Whether to enable the IPC metrics server used by iris-mcp-server monitor (default: true).
--help Prints command information.

The following are the CLI flags for the monitor subcommand (see Monitoring and Telemetry for details):

iris-mcp-server monitor subcommand flags
Flag Description and Example
--pid pid The process to monitor, where pid is the process ID.
--socket path The IPC socket to connect to, where path is the IPC path.

Transport Modes

The transport mode is the protocol the iris-mcp-server uses to communicate with an MCP client.

All of the following examples set up a configuration file with the relevant settings. After setting up this configuration file, you can start the iris-mcp-server with:

iris-mcp-server --config config.toml run

stdio

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

Note:

This transport mode is incompatible with the stderr logging output location.

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   = "/path/to/iris-mcp.log"

http

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

https

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"

Allowed Hosts and Networks*

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"]

Connection Pools

Each InterSystems IRIS instance has its own WebSocket session pool, the size of which is determined by pool = { min, max }, where:

  • min — The number of connections that should be kept in the pool when idle.

  • max — The maximum number of connections in the pool. As a general rule, this value should be at least as large as the number of simultaneous tool calls you expect to have.

Each pool slot is one WebSocket connection to InterSystems IRIS (one concurrent, in-flight tool call per slot).

The following example shows how to use the pool field:

[[iris]]
name      = "production"
server    = { host = "iris.example.com", port = 1972, username = "CSPSystem", password = "SYS" }
pool      = { min = 5, max = 20 }    # up to 20 concurrent tool calls
endpoints = [{ path = "/mcp/prod" }]

Session Lifetime

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" }]

Authentication

A connection between iris-mcp-server and InterSystems IRIS consists of two different authentication layers. For the purposes of the iris-mcp-server, you must authenticate to both layers:

  1. Layer 1 — Authentication by iris-mcp-server to the InterSystems IRIS superserver

  2. Layer 2 — Authentication by the MCP client to an MCP server endpoint

Superserver Authentication (Layer 1)

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

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

MCP Client Authentication to an MCP Server Endpoint (Layer 2)

An MCP client can only authenticate to an InterSystems IRIS MCP endpoint with the authentication methods allowed by that endpoint; when you configure an MCP endpoint (System Administration > Security > Applications > MCP Servers), the Allowed Authentication Methods determines what types of credentials the endpoint will accept from the MCP client.

For the stdio transport mode, you can either set the endpoint to be unauthenticated or use a password with some default credentials for use when the client doesn't provide their own. The following example shows how to do this in the iris-mcp-server configuration file:

endpoints = [
  # Unauthenticated (should only be used with the stdio transport mode, if at all).
  { path = "/mcp/myservice0" },

  # Password or LDAP
  { path = "/mcp/myservice1", username = "myuser", password = "mypassword" },

  # Password or LDAP with environment variables
  { path = "/mcp/myservice2", username = "@{env:IRIS_APP_USER}", password = "@{env:IRIS_APP_PASSWORD}" },

  # OAuth with a fixed bearer token from an environment variable
  # For standard OAuth flow where the client dynamically retrieves
  # the OAuth token, use http or https transport modes instead
  { path = "/mcp/myservice3" bearer = "@{env:IRIS_TOKEN}"},
]

For HTTP-based (remote) transport modes, iris-mcp-server forwards any credentials it receives from your MCP client directly to your MCP endpoint in InterSystems IRIS.

For example, if your MCP server endpoint's Allowed Authentication Methods is Password, you can authenticate from your MCP client with the Basic Authorization scheme, providing a base64-encoded username and password in your request. For OAuth, you would use the Bearer scheme. The exact method for configuring these varies between MCP clients; refer to your MCP client's documentation for details.

If you don't want to authenticate from your MCP client to your remote iris-mcp-server, you can also provide credentials in the configuration file like with the stdio transport mode above.

Important:

The credentials specified by endpoints only apply in cases where MCP clients do not already provide credentials themselves inside the Authentication header of their request; if an MCP client sends credentials, they overwrite the ones specified in endpoints.

This means that these credentials act as those of a "default" user when no credentials are provided by the client and effectively make the endpoint public, which is unsafe for remote MCP endpoints. While MCP clients that provide incorrect credentials are still rejected, any MCP client that provides no credentials at all will have access to the MCP endpoint using the credentials you provided in endpoints.

endpoints = [
  # Unauthenticated remote MCP; do not use in production
  { path = "/mcp/myservice0" },

  # Password or LDAP
  { path = "/mcp/myservice1", username = "myuser", password = "mypassword" },

  # Password or LDAP with environment 
  { path = "/mcp/myservice2", username = "@{env:IRIS_APP_USER}", password = "@{env:IRIS_APP_PASSWORD}" },

  # OAuth with a fixed bearer token from an environment variable
  { path = "/mcp/myservice4" bearer = "@{env:IRIS_TOKEN}"},
]

OAuth Integration

You can configure InterSystems IRIS to be your OAuth resource server and have it protect MCP endpoint through a resource mapping:

  1. In System Administration > Security > System Security > Authentication/Web Session Options, verify that Allow OAuth2 authentication is selected.

  2. In System Administration > Security > Applications > MCP Servers, select your MCP server endpoint.

  3. In Allowed Authentication Methods, select OAuth2.

  4. Configure InterSystems IRIS as an OAuth resource server.

  5. Verify that the resource server is responsible for the MCP Server endpoint. This is specified in the resource mapping (System Administration > Security > OAuth 2.0 > Resource Server > Mappings) and its associated Key, which should either contain the name of the name of your MCP server endpoint (for example, /mcp/myservice) or a * (asterisk) which matches all web application and MCP server endpoint names.

OAuth Passthrough (Remote MCP)

When iris-mcp-server uses an HTTP-based transfer mode (that is, http or https), each MCP client session contains an Authorization header. iris-mcp-server forwards this header value, unchanged, to the InterSystems IRIS MCP endpoint in every request within that session. This is called OAuth Passthrough. Any valid scheme works without server-side changes.

OAuth Passthrough is always active for the HTTP-based transfer modes; the credentials provided by the endpoints in the configuration file act as a fallback only when no Authorization header arrives from the MCP client.

Note:

For JWT tokens, expired Bearer tokens (indicated by its exp claim) are rejected by iris-mcp-server before they reach InterSystems IRIS; this optimization is not available for opaque tokens.

iris-mcp-server as an OAuth Proxy

If you use InterSystems IRIS as your OAuth authorization server, you can configure iris-mcp-server to act as its proxy for all OAuth flows sent to InterSystems IRIS. It does this by providing its own OpenID Connect Discovery endpoint, rewriting the endpoints to point to iris-mcp-server instead of your InterSystems IRIS instance, keeping the InterSystems IRIS instance hidden.

With iris-mcp-server as a proxy for your resource server, the authentication process is as follows:

  1. The MCP client sends a request to the OpenID Connect Discovery endpoint (RFC 8414Opens in a new tab) exposed by the iris-mcp-server (GET /.well-known/oauth-authorization-server).

  2. iris-mcp-server retrieves the authorization server metadata from InterSystems IRIS, rewrites all endpoint URLs to point to iris-mcp-server (replacing the InterSystems IRIS host), and returns this rewritten version to the MCP client.

  3. The client uses the discovered endpoints to obtain a token. All requests go to the iris-mcp-server proxy, which sends them to InterSystems IRIS.

  4. The client uses the resulting Bearer token for MCP calls: iris-mcp-server forwards the token to InterSystems IRIS using OAuth Passthrough.

To enable this behavior:

  1. Configure InterSystems IRIS as a resource server.

  2. Add an [oauth] section to your configuration file. In the example below, production refers to the name of the InterSystems IRIS instance specified in the [[iris]] section of the configuration file (iris[0].name); this instance acts as the authorization server for all MCP endpoints:

    [oauth]
    iris = "production"    # name of the [[iris]] section whose InterSystems IRIS instance is the authorization server
    
    # Optional: public base URL for URL rewriting in the AS metadata response.
    # If omitted, derived from the incoming Host header.
    # Set explicitly when running behind a reverse proxy that does not forward Host accurately.
    host = "https://mcp.example.com"
    
    # Optional: path to fetch AS metadata from InterSystems IRIS.
    # Defaults to /.well-known/oauth-authorization-server (RFC 8414 standard).
    # Override when the AS metadata is served at a non-standard path.
    # well_known_path = "/custom/as-metadata"
    
    # Optional: additional URL prefixes to allow through the proxy beyond those
    # listed in the AS metadata. Use for IRIS login pages served outside the
    # standard OAuth prefix when supporting the Authorization Code flow interactively.
    # allowed_paths = ["/csp/sys/auth"]
    
Note:

InterSystems IRIS must be configured with its public issuer URL (the value of host, which is the URL that MCP clients use to reach the iris-mcp-server) so that the issuer field in the authorization server metadata matches the iss claim in issued tokens; while iris-mcp-server is capable of rewriting endpoint URLs, it cannot rewrite iss claims. A mismatch in the issuer and the iss claim will cause clients that validate the iss to reject otherwise valid tokens.

Using TLS*

iris-mcp-server is associated with two connections:

  • Superserver-side — The connection from iris-mcp-server (client) to InterSystems IRIS (server). In this case, iris-mcp-server must verify the certificates presented by InterSystems IRIS. InterSystems IRIS certificates are configured with a TLS configuration. This is configured inside the [[iris]] part of the iris-mcp-server configuration file.

  • Server-side — The connection from MCP clients (client) to iris-mcp-server (server). This is configured inside the [mcp] part of the iris-mcp-server configuration file.

The sections below detail how to encrypt each connection.

For reference, a completed configuration for TLS that encrypts both connections (superserver-side and server-side) should look something like this:

[mcp]
transport = "https"
host = "192.0.2.0"
port = 38991
# The certificates that iris-mcp-server presents to MCP clients
tls = { cert = "/path/to/mcp-server.crt", key = "/path/to/mcp-server.key" }

[[iris]]
name   = "demo"
server = { host = "localhost", port = 51774, username = "CSPSystem", password = "SYS" }
# The certificate iris-mcp-server uses to verify the identity of the InterSystms IRIS instance
tls    = { ca_cert = "/path/to/iris-ca.crt" }
pool   = { min = 2, max = 5 }
endpoints = [
  { path = "/mcp/myservice" },
]

[logging]
level  = "debug"
output = "file"
file   = "/path/to/my-iris-mcp.log"

Superserver-Side TLS

The presence of the tls field enables TLS. To encrypt the superserver-side connection with TLS (that is, the one between iris-mcp-server and InterSystems IRIS), add tls = {} to [[iris]]. iris-mcp-server uses your system's trusted CAs:

[mcp]
transport = "https"
host = "0.0.0.0"
port = 8443
  
[[iris]]
tls = {}

If you want to use custom CA certificates, you can add their paths to tls:

  • 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.

Note:

All certificates and keys must be in PEM format.

Then, for your InterSystems IRIS instance, create a Server type TLS configuration that contains a server certificate trusted by the CA certificate you specified inside your configuration file above. For mutual TLS, this TLS configuration should also:

  • Require or Request Client certificate verification

  • Specify a CA certificate in File containing trusted Certificate Authority certificate(s) that verifies the identity of the iris-mcp-server client certificate

Server-Side TLS

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]:

[mcp]
transport = "https"
host = "192.0.2.0"
port = 38991
# The certificates that iris-mcp-server presents to MCP clients
tls = { cert = "/path/to/mcp-server.crt", key = "/path/to/mcp-server.key" }

Tool Discovery

Before iris-mcp-server can make tools available to MCP clients, it needs to fetch the list of available tools from an InterSystems IRIS MCP endpoint. This process of fetching tools is called discovery.

Discovery is deferred until the first MCP client connects to iris-mcp-server. When it does, iris-mcp-server discovers the tools from each MCP server endpoint in InterSystems IRIS.

If discovery fails (for example, if the InterSystems IRIS instance is unreachable), existing tool registrations are used as a fallback; iris-mcp-server makes a new discovery attempt on the next tool call.

Smart Discovery (RAG)

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.

Note:

The embedding model is automatically downloaded from HuggingFace on first use (~25 MB).

To enable this feature in your configuration file:

[features]
smart_discovery = true

Tool Refresh

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" }]

Endpoint Auto-Discovery

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

Tool Name Prefixing

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.

Note:

Tool name prefixes are applied even if iris-mcp-server is only connected to a single endpoint.

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

Tool Name Prefix Examples
MCP server endpoint name Service ID prefix Example tool name
/mcp mcp mcp_ExecuteQuery
/mcp/database mcp_database mcp_database_ExecuteQuery
/mcp/myapp mcp_myapp mcp_myapp_GetCustomer

Reconnection

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" }]

Monitoring and Telemetry

iris-mcp-server provides several features for monitoring and telemetry.

Real-Time Monitoring

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.

Logging

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"

OpenTelemetry Tracing

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
    

Troubleshooting

The iris_status Diagnostic Tool

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.

Important:

iris_status should only be used in a development environment.

Connection Failures

  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.

Authentication Failures (403)

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.

Connected, But Tools Do Not Appear

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.

Verifying Tool Discovery

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

Particular Tool Not Shown

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.

Secret and Credential Resolution Failures

If your iris-mcp-server exits at startup with a secret resolution error, verify that the environment variables you reference (@{env:VAR}) are set.

FeedbackOpens in a new tab