Welcome back to a series of introductory articles on AI Hub, the new product feature currently in an early access program! (links: EAP Site for download, documentation)

In the last article, we covered how to create agents and agent tools directly in ObjectScript using the new %AI classes. However, sometimes, instead of creating a new agent, you just want to add some custom tools to an existing agent so you can ask your local claude code, codex, copilot or other agent of choice to query your data directly. This is where MCP Servers might come in.

In this guide, we will walk through how you can create your own MCP Servers to access your data.

Disclaimer: AI Hub is an early access preview, with features likely to change before production releases, any issues identified can be raised as issues on the documentation GitHub repo linked above. The EAP preview is not to be used in production settings.

A very brief intro to MCP

I'm going to keep this brief because there are loads of other good articles on MCP Servers Model context protocol (I recommend starting with this article from @pietro.DiLeo or this brilliant introductory video from InterSystems President Don Woodlock).

Model Context Protocol is a transport protocol allowing external tools to be added to an agent. There is a discovery 'handshake' where the MCP server sends a list of tools to the MCP Client. After the tools are discovered, the agent can send requests for tool executions, including parameters, to the MCP server, which executes the tool call and returns the result.

MCP servers can be remote servers, i.e. running on a different machine to a client, this usually uses a streamable http/https connection or Server-Side Events. Or MCP servers can be local servers, i.e. running on the same machine, usually using a stdio connection.

An important distinction

AI hub allows you to create custom MCP servers within your IRIS environment, allowing agents to access or monitor your IRIS databases, productions and statuses. It is not a pre-configured MCP server. 

If you are looking for a developer tool which gives your agent free access to an IRIS environment to speed up development, you may be looking for a pre-configured MCP server. If you are looking to create production MCP servers which are secure, auditable and fit within IRIS's governed security environment, AI Hub is what you are looking for. 

There are many pre-configured MCP servers which provides tools for developing with IRIS, including iris-agentic-dev, an MCP tool and skills library created by @tomd. This is a separate project from AI Hub, so look out for an article about this! 

MCP in AI Hub

In the previous article, we covered creating agent tools and toolsets, here we will go through how to serve these tools as an MCP server using both HTTP and STDIO. The code covered in this article is available in the ai-hub-dev-template which is a nice place to start if you want to play around with IRIS AI hub.

Before getting to this though lets, take a look at the architecture of an AI Hub MCP server:

MCP Clients (blue) communicates with iris-mcp-server to bridge the gap between the MCP calls (discovery and execution) and IRIS. This binary then communicates with an MCP Server web application, defined using %AI.MCP.Service as a dispatch class. This dispatch class then routes the tool calls to ObjectScript tool classes which can then operate on IRIS databases. This diagram skips the reverse routing (returning the tool responses) as well as the initial handshake between the MCP Client and the iris-mcp-server.

There are more details on this architecture in the documentation, but this simplified view covers the key elements that we need to define. These are:
1. Tools / Toolsets
2. %AI.MCP.Service dispatch class
3. MCP Application
4. iris-mcp-server configuration
5. MCP Client connection

Lets go through these one by one.

1. Tools

We define tools or toolsets by extending %AI.Tool or %AI.ToolSet, this was covered in detail in Part 1, so I'm going to skip over this.

2. Defining the dispatch class

To define an MCP Service dispatch class, we just need to extend %AI.MCP.Service and point it at the tools/toolsets we want to include in the SPECIFICATION parameter:

Class Sample.MCPService Extends %AI.MCP.Service
{
    Parameter SPECIFICATION = "Sample.ToolSet";
}

We could include multiple tool/toolset classes by adding the classes as a comma-separated list, but here we've kept it simple with just one. 

3. Creating the MCP Application

Next up, we create an MCP server application. Like other web applications this can be managed from the management portal, or programmatically with the Security.Applications class. In this case, there is a new MCP server management portal in the Management Portal:

But everything else will feel familiar to developers creating Web Applications in IRIS. 

The key points are to give an endpoint (e.g /mcp/sample) and the MCP Service Class we created earlier. I won't show the programmatic version, but this can be done with Security.Applications, just set the Type value to 18 to register it in the MCP Server menu.

At this point, you can see the JSON description of tools being served at http://localhost:52773/mcp/sample/v1/services. This means it is discoverable by the iris-mcp-server binary, it is not discoverable directly by an mcp client. 

4. iris-mcp-server configuration

The iris-mcp-server binary takes a configuration file when it is run, this is run with the following command:

iris-mcp-server -c config.toml run

We'll get to exactly how this command is actually used in the next section (MCP Client), but for now we are going to focus on the config file.

The first thing to do when writing your config file is to set your connection to IRIS - this requires the credentials for a gateway-privileged user e.g. CSPSystem, the superserver port used for web-gateway (default 1972) and your MCP endpoints:

[[iris]]
name = "local"
server = { host = "localhost", port = 1972, username = "SuperUser", password = "SYS" }
endpoints = [
    {path = "/mcp/sample" }
]

Then you have to define your transport. This is done in the [mcp] block.

For stdio, you just need set the type of transport:

[mcp]
transport="stdio"

For http/https, you also have to give the host and port:

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

This port is a different port to the management portal and will be used only for this MCP server. This is a common mistake because, although you can find the tool catalog on the management portal port at http://localhost:52773/mcp/sample/v1/services, to actually connect to the MCP server you have to set a different port to communicate to the iris-mcp-server bridge.

Authentication

We set the web application to unauthenticated above, but this should be avoided for production use. To add authentication, first set the web application to password authenticated. You can add a username and password or a bearer token to the endpoint:

[[iris]]
name = "local"
server = { host = "localhost", port = 1972, username = "SuperUser", password = "SYS" }
endpoints = [
    {path = "/mcp/sample", username="SuperUser" password="SYS" }
]

If you are using an HTTP/HTTPS connection, you can also choose to not authenticate here, and instead handle authentication in the requests from the MCP client, this will be shown in the connecting from a client setting below.

Other settings

There are loads more settings to configure here, like the setting up OAuth, using environment secrets rather than hard-coding settings, configuring logging and telemetry and enabling smart tool discovery. To get more details on this, there is a full guide on the iris-mcp-server usage, but for basic usage you just need to define [[iris]] and [mcp].

5. Connecting from an MCP Client

The method for adding an MCP server will differ depending on which client you are using, but in general there will be an option somewhere in your agent customization settings to add an MCP server. For example, to set up an MCP server on GitHub Copilot, type >MCP: Add Server... into the VS Code Search bar, or for Claude Code, you can run claude mcp add.... 

The first option will likely be a choice between stdio or http(s) transport. These have quite different connection methods so lets tackle them individually.

 

Stdio

To use a stdio mcp server, you add /path/to/iris-mcp-server as the executable. The default location for this in a docker container is /usr/irissys/bin.

You also need to add arguments for the stdio config file config_stdio.toml and the run command:

/usr/irissys/bin/iris-mcp-server -c config_stdio.toml run

As the authentication is is included in the config file, this is all that is required.

Note, the iris-mcp-server binary has to be on the same machine (or container) as your MCP client!

 

HTTP

To connect to a remote HTTP MCP server from an MCP client, you first need to start the iris-mcp-server transport by opening a shell and running:

iris-mcp-server -c config_http.toml run

Unlike the STDIO connection, this needs to be continuously running for the HTTP connection to be usable.

With this running, we can then add this server to our MCP client by selecting HTTP as the transport or type, and giving the server URL: http://localhost:8080/mcp/sample.

If we wanted to set authentication at the MCP connection level (rather than the configuration level detailed above), we use standard HTTP authentication headers, like Basic base64(Username:Password) or Bearer <token>. The following Python snippet shows an example of connecting to an MCP server using Langchain's MultiServerMCPClient:

import base64
from langchain_mcp_adapters.client import MultiServerMCPClient

AUTH_HEADER = base64.b64encode(b"SuperUser:SYS").decode("utf-8")
async def get_tools():
    client = MultiServerMCPClient(
        {
            "minimal": {
                "transport": "http",
                "url": "http://localhost:8080/mcp/sample",
                "headers": {"Authorization": f"Basic {AUTH_HEADER}"},
            }
        }
    )

    tools = await client.get_tools()
    return tools

 

Conclusions

We've reached the end of Part 2 of this series! It has been a long part, so well done if you have got this far. Hopefully this guide will give you the confidence to use the AI Hub preview to start building your own MCP servers inside IRIS, giving agents secure and governed access to your IRIS instance.

If you want to see example code from this article, it is all included in the ai-hub-dev-template on open exchange. This is an example docker project that you can easily clone and use to start working with AI Hub on your local machine. In it, there is sample MCP server and as well as example code to programmatically create the MCP Server Web Application.