{"slug": "model-context-protocol-mcp-with-intersystems-iris-from-zero-to-hero", "title": "Model Context Protocol (MCP) with InterSystems IRIS - From Zero to Hero", "summary": "A developer demonstrated building a custom Model Context Protocol (MCP) server in Python integrated with the intersystems-irispython package, showing how Anthropic's open MCP standard can connect AI coding assistants like Claude, GitHub Copilot and Cursor to InterSystems IRIS data sources. The writeup walks through MCP's client-host-server architecture, JSON-RPC 2.0 messaging, and its three core server primitives, using the uv package manager to scaffold a reproducible Python project.", "body_md": "Today, coding assistants like Claude, GitHub Copilot and Cursor have transformed the way developers write code. However, these tools are limited by being isolated from the systems and data sources that developers work with daily. This limitation can be overcome through the **Model Context Protocol (MCP)**, an open standard designed to connect AI assistants to external data sources and tools in a secure and standardized way.\n\nIn this review article, we'll explore the current state-of-the-art regarding the MCP within the InterSystems ecosystem. Moreover, we will examine how this open standard connects AI assistants to external data sources, presenting a first example of a custom MCP server developed in Python and integrated with the `intersystems-irispython` package.\n\nTable of Contents\n\nThe **Model Context Protocol (MCP)** was introduced by **Anthropic** on November 25, 2024 [\\[1\\]](https://www.anthropic.com/news/model-context-protocol) as open-source with the goal of connecting AI systems to data sources, replacing fragmented integrations. Before MCP, every AI application required custom integrations to access each data source, like a database or an API. MCP solves this by providing a single, standardized protocol that any AI application can use to connect to compatible servers. \n\nThe protocol addresses three key challenges:\n\n**Official Resources:**\n\nMCP follows a **client-host-server architecture** [\\[5\\]](https://modelcontextprotocol.io/docs/learn):\n\nEach host can create multiple clients, with each client maintaining a **1:1 dedicated connection** with its corresponding server. \n\nFor example, Cursor acts as an MCP Host. When Cursor establishes a connection to an MCP server it instantiates an MCP client object that maintains the connection to that specific MCP server. When Cursor later connects to a different MCP server, it instantiates an additional MCP client object to maintain the new connection.\n\nYou can find the original image source [here \\[6\\]](https://mcpcat.io/blog/mcp-server-client-host/).\n\nMCP supports two transport mechanisms:\n\nIn MCP, the message structure and semantics is based on **JSON-RPC 2.0** protocol [\\[7\\]](https://www.jsonrpc.org/). All communication follows a structure like the following:\n\nJSON-RPC 2.0\n\n```\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 1,\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"query_database\",\n    \"arguments\": {\n      \"sql\": \"SELECT * FROM Patient LIMIT 10\"\n    }\n  }\n}\n```\n\nMCP defines three core primitives that servers can expose [\\[5\\]](https://modelcontextprotocol.io/docs/learn):\n\nBefore diving into code examples, let's understand how to build MCP servers in Python.\n\nMCP provides official SDKs for multiple programming languages, including TypeScript, Java, and Python [\\[8\\]](https://modelcontextprotocol.io/docs/sdk). In this article, we'll focus on **Python** as it's widely used in the InterSystems community and integrates well with IRIS through the Native SDK [\\[9\\]](https://docs.intersystems.com/irislatest/csp/docbook/DocBook.UI.Page.cls?KEY=PAGE_python_native).\n\nBefore talking about code, we should understand how to create a proper environment for our application, which won't just contain the Python code, but it also includes:\n\nTo set up the environment we will use the `uv` Python package manager, a modern Python package manager that simplifies environment creation, dependency resolution, and reproducible execution of MCP servers [\\[10\\]](https://docs.astral.sh/uv/concepts/projects/dependencies/).\n\nYou can initialize properly your folder structure for your MCP project using the `uv init` statement.\n\nInit package with uv\n\nYou can initialize a new project with:\n\n```\nuv init --package my-mcp-server\n```\n\nWhere the `--package` option tells `uv` to create a Python package. \n\nThis command generates the following folder tree:\n\n```\nmy-mcp-server/\n├── pyproject.toml      \n├── README.md\n├── .python-version     \n└── src/\n    └── my_mcp_server/\n        └── __init__.py\n```\n\nThe `.python-version` file specifies which Python version the project should use.\n\nThe `__init__.py` file marks a directory as a Python package. Since Python packages are expected to contain one or more Python modules, which are directories containing an `__init__.py`, each subfolder of the project needs an `__init__.py` (can be empty) to be importable as a package.\n\nThe `pyproject.toml` contains the metadata and configuration for the project. It defines how the package is built, its dependencies, and the Python version requirements. It is composed by several sections like:\n\n`[build-system]`: specifies how the package is built. `uv` uses `[project]`: contains metadata and dependency definitions\nThis is an example of `pyproject.toml`:\n\n```\n[build-system] \nrequires = [\"hatchling\"] \nbuild-backend = \"hatchling.build\" \n\n[project] \nname = \"my-mcp-server\" \nversion = \"0.1.0\" \ndescription = \"\" \nreadme = \"README.md\" \nrequires-python = \">=3.12\" \ndependencies = []\n```\n\nAfter creating the structure, you can add dependencies to the project using the `uv add` statement.\n\nAdd server dependencies\n\nYou can use the `uv add` statement to add dependencies:\n\n```\nuv add fastmcp intersystems-irispython requests\n```\n\nThis command:\n\n`[project.dependencies]` in `pyproject.toml`\n`uv.lock` file. This is used to recreate the environment while building your project on another machine.`.venv/`\nAfter this step, the `pyproject.toml` will contain a new section for all your dependencies:\n\n```\n[project]\n...\ndependencies = [\n    \"fastmcp>=3.2\",\n    \"intersystems-irispython>=5.3\",\n    \"requests>=2.32\",\n]\n```\n\nWhile the `pyproject.toml` contains all the direct dependencies, the `uv.lock` is a file that contains all resolved dependencies, namely the exact versions of all the direct and transitive dependencies in the project. \n\nAt build time, instead of resolving dependencies again, `uv` reads `uv.lock` and installs exactly what’s written there. \n\nThe `uv.lock` file looks like the following:\n\n```\n[[package]]\nname = \"fastmcp\"\nversion = \"3.2.1\"\ndependencies = [\n    \"pydantic\",\n    \"typing-extensions\",\n]\n```\n\nFinally, it's time to add an entry point to start the server.\n\nAdding an entry point for the MCP server\n\nTo make the MCP server executable, define a CLI entry point in `pyproject.toml`:\n\n```\n[project.scripts]\nmy-mcp-server = \"my_mcp_server.entrypoint:main\"\n```\n\nThis maps a command name (`my-mcp-server`) to a Python function using the format `module.path:function`. So, when the command is executed, Python imports `my_mcp_server.entrypoint` and runs the `main()` function.\n\nLet's now take a look at the available packages that we can use to implement the MCP server. While the official `mcp` package provides the core protocol implementation [\\[12\\]](https://pypi.org/project/mcp/), `FastMCP` package has emerged as one of the easiest and fastest frameworks for building MCP servers with Python [\\[13\\]](https://gofastmcp.com/). This article will provide the minimal structure of an MCP server using FastMCP. \n\nA server is defined by three main steps:\n\ninitializing the server\n\ndefining tools, resources and prompt decorating the functions\n\nrunning the process\n\nFastMCP first example\n\n``` python\nfrom fastmcp import FastMCP\n\n# 1. Create the MCP server instance\nmcp = FastMCP(name=\"My MCP Server\")\n\n# 2. Define tools, resources and prompts using decorators\n@mcp.tool\ndef my_tool(param: str) -> str:\n    \"\"\"Description of what this tool does. This text is sent to the LLM.\"\"\"\n    return f\"Result: {param}\"\n\n# 3. Run the server (defaults to STDIO transport)\nif __name__ == \"__main__\":\n    mcp.run()\n```\n\nLet's see how to implement each primitive type:\n\n`@mcp.tool` decorator. Note that the docstring becomes the tool's description shown to the AI. In fact, when using this decorator, FastMCP automatically generates a JSON schema from Python type hints and docstrings, telling the AI exactly how to use the function.\nTools Example\n\n``` php\n@mcp.tool\ndef query_database(sql: str) -> str:\n    \"\"\"\n    Execute an SQL query against the database.\n    \n    Args:\n        sql: The SQL query to execute\n    \n    Returns:\n        Query results as a string\n    \"\"\"\n    # Logic to connect to IRIS and execute SQL goes here\n    return execute_query(sql)\n```\n\n`@mcp.resource(\"uri\")` decorator and assigning it a unique URI.\nResource Example\n\n``` php\n@mcp.resource(\"resource://database/schema\")\ndef get_schema() -> dict:\n    \"\"\"Provides the database schema information to help the AI write better SQL.\"\"\"\n    return {\n        \"tables\": {\n            \"Patient\": [\"id\", \"first_name\", \"last_name\", \"dob\"],\n            \"Encounter\": [\"id\", \"patient_id\", \"date\", \"reason\"],\n            \"Observation\": [\"id\", \"encounter_id\", \"type\", \"value\"]\n        },\n        \"version\": \"1.0\",\n        \"storage_type\": \"relational\"\n    }\n```\n\n`@mcp.prompt` decorator that can guide the AI assistant to perform specific repetitive tasks like writing queries or importing data into the database.\nPrompt Example\n\n``` php\n@mcp.prompt()\ndef sql_assistant() -> str:\n    \"\"\"A prompt template for IRIS SQL query assistance.\"\"\"\n    return \"\"\"You are an expert SQL developer specializing in InterSystems IRIS.\n    When writing queries:\n    - Use proper IRIS SQL syntax (e.g., handle schema names correctly).\n    - Favor performance-optimized indices.\n    - Explain your reasoning if the query is complex.\"\"\"\n```\n\nAI development tools are rapidly evolving from simple chat interfaces into sophisticated orchestrators capable of interacting with your local environment and remote servers by adopting the MCP protocol. Currently, while several platforms now support the protocol, the setup process is generally standardized across them.\n\nMost popular platforms nowadays are:\n\n**Cursor**: An AI-powered IDE built on Visual Studio Code that includes AI agent's capabilities and MCP integrations into the code editor [\\[14\\]](https://cursor.com/).\n\n**Claude Desktop**: Anthropic's official client, which uses MCP to give Claude \"skills\" like searching your local files or databases [\\[15\\]](https://claude.com/download).\n\n**Claude Code**: A CLI-based agent that can integrate MCP servers directly from the terminal [\\[16\\]](https://claude.com/product/claude-code).\n\n`.cursor/mcp.json` file within your repository.`~/.cursor/mcp.json` on macOS/Linux or the equivalent AppData path on Windows).`claude_desktop_config.json`, that you can find within the application itself using the menu\nThe following JSON structure shows how to connect Cursor or Claude to an IRIS MCP server:\n\n```\n{\n  \"mcpServers\": {\n    \"my-server-name\": {\n      \"command\": \"executable-or-runtime\",\n      \"args\": [\"path/to/script-or-package\", \"--option\", \"value\"],\n      \"env\": {\n        \"KEY_1\": \"value-1\",\n        \"KEY_2\": \"value-2\"\n      }\n    }\n  }\n}\n```\n\nEvery MCP server configuration is based on a few key fields that tell the AI how to launch and communicate with the server.\n\nLet's look at the JSON fields to understand how this configuration works:\n\n`mcpServers`: The root object that lists all your connected servers. You can have multiple servers running simultaneously (for example: one for IRIS, one for Google Drive, one for Atlassian, etc.).`command`: The command used to start the server. Common examples include `python`, `node`, `uvx`, or `npx`. In particular, use `args`: An array of arguments passed to the command. This usually includes the MCP server file path or the name of a package to execute.`env`: An array containing your environment variables. This is the standard way to pass sensitive or environment-specific data like hostnames, port numbers, and credentials without hardcoding them into the server logic itself.\nOnce you have this configured, the AI assistant can directly interact with your IRIS database, execute queries, and access schema information without you manually copying and pasting context.\n\n`uv run`:\n\n```\n{\n  \"command\": \"uv\",\n  \"args\": [\"run\", \"<mcp-server-name>\"],\n  \"env\": { \"...\": \"...\" }\n}\n```\n\nThe CLI is launched directly from your live source tree, so any change to a tool, prompt, or resource is picked up the next time you reload the server in the client, without having to rebuild or reinstall. This is the only mode that lets in-progress edits take effect immediately.\nOnce the repo is pushed, anyone with `uv` installed can run the server without cloning it by pointing `uvx` at the GitHub URL:\n\n```\n{\n  \"command\": \"uvx\",\n  \"args\": [\n    \"--from\", \"git+https://github.com/<repository>.git\",\n    \"<mcp-server-name>\"\n  ],\n  \"env\": { \"...\": \"...\" }\n}\n```\n\nThe first time the client launches,\n\n```\n{\n  \"command\": \"uvx\",\n  \"args\": [\"<mcp-server-name>\"],\n  \"env\": { \"...\": \"...\" }\n}\n```\n\nPublishing on PyPI\n\nBump the version (PyPI rejects re-uploads of an existing version)\n\n```\n# Use --bump patch / minor / major depending on the change\nuv version --bump patch\n```\n\nBuild the wheel and the source distribution into ./dist\n\n```\nuv build\n```\n\nUpload to PyPI using an API token\n\n``` js\n#    Export the token as an env var so it does not end up in shell history\n#    uv publish reads it automatically from UV_PUBLISH_TOKEN. \nexport UV_PUBLISH_TOKEN=pypi-<your-token>     # Linux / macOS / Git Bash \n$env:UV_PUBLISH_TOKEN = \"pypi-<your-token>\"   # PowerShell \nuv publish\n```\n\nNowadays we already have several example of MCP servers working with InterSystems IRIS. Since IRIS is a multi-model database, it’s a perfect candidate for this protocol. Instead of just giving an AI your code, you’re giving it a live connection to your data, your globals, and your system metrics.\n\nSeveral developers have shared MCP implementations or MCP-related tools on the InterSystems Developer Community. Among these, the following:\n\n`.int`, `.mac`, `.inc`) directly from the IRIS server.\n[InterSystems IRIS AI Hub \\[22\\]](https://github.com/intersystems-community/ai-hub-eap): currently in Early Access and recently presented at READY 2026, it provides a unified SDK and MCP Server integration to securely connect AI models and external agents with InterSystems IRIS business logic.\n\nFeel free to cite in the comments all the applications and developers you believe worth to be mentioned.\n\nWhile the community tools are excellent, you may eventually need a server tailored to your specific application logic or you may want to understand how the previously mentioned tools work. In this section I'm providing an example of how to implement an MCP server to work with InterSystems IRIS.\n\nTo build an MCP server for InterSystems IRIS I recommend you to follow two main approaches:\n\n`intersystems-irispython` is the official Python package to connect with InterSystems IRIS providing a lightweight interface to access through Python all the resources once only available to ObjectScript, like Globals or Class Methods. This is best for heavy data operations, manipulating Globals, calling existing Business Logic and high-speed SQL execution.`/api/atelier/`) designed specifically for source code management. This was originally built for the Atelier IDE (and now it is used by the InterSystems Server Manager VS Code extension) and it is useful to work with source code files, compile classes, or manage development workflows. `mcp.json` snippets for Cursor and Claude Desktop in each of the three distribution modes, the list of every tool and prompt with example arguments refer to the repository's README.`sql.py`)` INFORMATION_SCHEMA`, can be used to retrieve information and helping the AI to write its own SQL queries later.`globals.py`)` iris_obj.isDefined(\"^GlobalName\")` to check global status (it returns `iris_obj.get(\"^Global\", sub1)` and `iris_obj.set(val, \"^Global\", sub1)` to get or set values from/in a global subscript.`class_methods.py`)` iris_obj.classMethodValue(\"Package.Class\", \"MethodName\", *args)`. This effectively turns your entire IRIS codebase into a library of functions the AI can call, including both custom and built-in methods.`atelier_api.py`)`.cls` class definition to explain the ObjectScript logic`interoperability.py`) \nThis implementation contains a limited number of use cases designed to explain of how to use both the native Python SDK and the Atelier API. Again, this example is not a complete implementation of services but rather a blueprint to be used as a guide to develop your own MCP server, tailored to satisfy the specific needs of your project.\n\nIf you want more information about how this blueprint work, check the related video on YouTube:\n\nThe following list contains all the cited sources", "url": "https://wpnews.pro/news/model-context-protocol-mcp-with-intersystems-iris-from-zero-to-hero", "canonical_source": "https://dev.to/intersystems/model-context-protocol-mcp-with-intersystems-iris-from-zero-to-hero-1nnb", "published_at": "2026-10-31 20:45:42+00:00", "updated_at": "2026-10-31 20:52:10.514926+00:00", "lang": "en", "topics": ["ai-agents", "agent-protocols", "developer-tools", "ai-tools", "artificial-intelligence"], "entities": ["Anthropic", "InterSystems IRIS", "Model Context Protocol", "Claude", "GitHub Copilot", "Cursor", "uv"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/model-context-protocol-mcp-with-intersystems-iris-from-zero-to-hero", "markdown": "https://wpnews.pro/news/model-context-protocol-mcp-with-intersystems-iris-from-zero-to-hero.md", "text": "https://wpnews.pro/news/model-context-protocol-mcp-with-intersystems-iris-from-zero-to-hero.txt", "jsonld": "https://wpnews.pro/news/model-context-protocol-mcp-with-intersystems-iris-from-zero-to-hero.jsonld"}}