AI agent as a production item
Agent inside the production: a new custom inbound adapter
(br.musketeers.InteropMCP.Agent.Adapter) turns an AI HUB agent into a
production item, published on the MCP endpoint next to the production's own
capabilities — no bespoke endpoint required.
Production-agnostic catalogue: the registry now distinguishes capability
from agent entries, carries each tool's description into the generated
method, and supports long-running services (AIGATEWAYASYNC) that report
their own outcome through GatewayInvocationId.
Traceability and identity: direct invocations now write a native
Ens.MessageHeader request/response pair, and the caller's identity
propagates through nested agent tool calls so guardrails classify by the
original agent.
Demo: agent REST service, admission policies, sample PDF invoices with
embedded-Python extraction, and an async batch service as reference
implementation.
Operations: bridge tool refresh disabled (it was answering 401 and dropping
tool registrations), CSP response timeout raised to 300s, single source of
truth for the restricted CNPJ list, and non-ObjectScript assets excluded from
the Docker build context.
Docs and tests: new article — the agent running directly in the production —
operations-guide sections for async services and agent attachment, plus
ObjectScript unit tests and a Python contract test pinning the published MCP
tool surface.
IRIS InteropMCP turns InterSystems Interoperability Productions into native
Model Context Protocol (MCP) servers. AI agents, corporate assistants and LLM-based
tools can invoke legacy Business Services through natural language — with per-tool security
guardrails and full audit — without rewriting a single line of integration code.
Built on the InterSystems AI HUB framework in ObjectScript and deployed as a containerized workload.
The AI Hub image is not on Docker Hub — you must download it from the InterSystems EAP Portal first, then load it locally.
Download the AI Hub image
.docker.tar.gz for your platform:
Load the image into Docker
You can download any AI Hub version from the EAP Portal. For convenience, use the same version as this repo (2027.1.0AI.109.0) — then skip step 3.
docker load -i /path/to/iris-community-2027.1.0AI.109.0-docker.tar.gz
Tip: The filename matches the tag, e.g.,
iris-community-2027.1.0AI.109.0-docker.tar.gz
Verify iris-main.log exists with correct ownership (idempotent)
[ -f iris-main.log ] || touch iris-main.log
sudo chown 51773:51773 iris-main.log && sudo chmod 666 iris-main.log && ls -la iris-main.log
# Expected: -rw-rw-r-- 1 51773 51773 out/date_size iris-main.log
Update the Dockerfile (only if using a different version)
The repo’s Dockerfile defaults to 2027.1.0AI.109.0:
ARG IMAGE=docker.iscinternal.com/docker-intersystems/intersystems/iris-community:2027.1.0AI.109.0
If you downloaded
2027.1.0AI.109.0above, skip this step — nothing to edit.
Otherwise, edit Dockerfile and change the ARG IMAGE=... line to match your loaded image tag.
Prepare credentials
Crie .env a partir de .env.example e corrija a senha da bridge:
cp .env.example .env && sed -i 's/^WG_PASS=change-me/WG_PASS=SYS/' .env
O
WG_PASSdeve serSYS(senha padrão do IRIS) para a bridgeiris-mcp-serverse conectar ao nó. Sem isso o catálogo fica vazio (names=[]) e chamadas de ferramentas falham comI/O error: early eof.
Exporte a credencial de autenticação do cliente para o opencode e outros clientes MCP:
export INTEROPMCP_BASIC="Basic $(printf 'mcp_demo:change-me' | base64 -w0)"
Adicione essa linha ao
~/.bashrcpara que o opencode (e outros clientes MCP) enviem o headerAuthorizationcorretamente. Essa variável é client-side — não é lida pelo container. Para persistir entre rebuilds, adicione ao~/.bashrce abra um novo terminal.
opencode.jsonlê{env:INTEROPMCP_BASIC}do ambiente do processo no startup.
A transientexporté perdida na reinicialização, e o rebuild do container não atualiza
~/.bashrc/.env(eles ficam fora da imagem). Persista em~/.bashrc, então abra um
novo terminal.
For a clean rebuild (recommended the first time or after changes):
docker compose down -v
docker compose build --no-cache
docker compose up -d
Wait for health and verify
docker compose logs -f
Look for Supervising mcp-server in ai-hub-mcp-launcher service.
Connect your AI coding assistant to the MCP endpoint
The MCP server runs at http://localhost:8080/mcp. Configure your preferred tool:
opencode (pre-configured in this repo)
opencode.json with InteropMCP configuredopencode
opencode.json):
"InteropMCP": {
"type": "remote",
"url": "http://localhost:8080/mcp",
"headers": { "Authorization": "{env:INTEROPMCP_BASIC}" },
"enabled": true
}
Claude Code
.mcp.json in the repo root:
{
"mcpServers": {
"interopmcp": {
"url": "http://localhost:8080/mcp"
}
}
}
GitHub Copilot (VS Code)
settings.json:
"mcp": {
"servers": {
"interopmcp": {
"url": "http://localhost:8080/mcp"
}
}
}
Test it
6.1 Invoke a tool — in your AI assistant’s chat:
Use the PayLookup tool with OrderId 88201 and CustomerId C-1

6.2 Verify in IRIS Management Portal
Ens.MessageHeader entry with the BS→BP→BO chainDemo.PayLookupService → Demo.AuditProcess → Demo.AuditOperation
6.3 Verify audit store (SQL):
Access the SQL portal at http://localhost:52773/csp/sys/exp/%25CSP.UI.Portal.SQL.Home.zen?$NAMESPACE=IRISAPP
SELECT * FROM br_musketeers_InteropMCP.Invocations ORDER BY InvocationId DESC
6.4 Verify demo audit payload:
docker exec -it ai-hub-dev-template-iris-1 iris session iris -U IRISAPP
Then run:
zwrite ^InteropMCP.Demo.AuditD
halt
MCP endpoint: http://localhost:8080/mcp
For more detailed information and additional examples, see InteropMCP: Turn your InterSystems IRIS productions into MCP tools for AI agents.
| Sintoma | Causa provável | Solução |
|---|---|---|
"InteropMCP Failed to get tools" |
INTEROPMCP_BASIC ausente/obsoleto no ambiente do opencode (~/.bashrc) |
printenv INTEROPMCP_BASIC; corrija o bloco no ~/.bashrc (derive do .env), abra um novo terminal e reinicie o opencode. Rebuild só como fallback |
"InteropMCP Failed to get tools" com INTEROPMCP_BASIC correto |
iris-mcp-server expõe iris_status com inputSchema vazio ({}), schema inválido para clientes MCP 2025-11-25 (opencode) |
Suba a bridge com run --status-tool false; o docker-compose.yml já faz isso no start e no supervisor |
| Bridge descobre 0 ferramentas | config_http.toml sem WG_USER/WG_PASS |
Crie .env a partir de .env.example e exporte INTEROPMCP_BASIC |
401 na descoberta |
Credencial da bridge ausente ou inválida | Verifique .env e `INTEROPMCP_BASIC=“Basic $(printf ‘mcp_demo:change-me’ |
403 na execução da ferramenta |
Usuário não é membro de InteropMCPRoles |
Use mcp_demo (entitled) em vez de mcp_demo2 (unentitled) |
| Bridge não sobe | Supervisor não reinicia sozinho | docker exec -d <container> sh -c '/usr/irissys/bin/iris-mcp-server -c /home/irisowner/dev/config_http.toml run --status-tool false > /tmp/mcp.log 2>&1' |
| Catálogo desatualizado após rebuild | Bind-mount sobrescreve GeneratedTools.cls |
O BuildCatalog roda durante o docker build; se necessário, re-rProvisione: docker exec <container> iris session IRIS -U IRISAPP < bootstrap-gateway.script |
readonly (autonomous),write (requires authorization) or critical (requires explicit human approval beforeEns.MessageHeader rows and a Visual Trace chain. The gateway keeps its own audit storebr.musketeers.InteropMCP.Invocations) and never writes into production structures.GetInvocationStatus for the outcome.flowchart TD subgraph Client["MCP Client"] A[MCP client / opencode] endsubgraph Bridge["MCP Bridge"] B[iris-mcp-server bridge :8080] end subgraph Gateway["MCP Gateway (Web app /mcp/interopmcp)"] C[Web app /mcp/interopmcp - Type 18] D[br.musketeers.InteropMCP.MCPService - %AI.MCP.Service] E[br.musketeers.InteropMCP.ToolSet] F[GeneratedTools + InvocationStatusTools] G[Guardrails] H[Invoker] end subgraph Production["Interop Production"] I[Business Service] J[AuditProcess - BP] K[AuditOperation - BO] end subgraph Storage["Storage & Audit"] L[^InteropMCP.Demo.AuditD payload] M[Ens.MessageHeader + Visual Trace] N[Invocations audit store] end A -->|JSON-RPC| B B --> C C --> D D --> E E --> F F --> G G -->|proceed| H H -->|fires BS only| I I -->|SendRequestSync| J J -->|SendRequestSync| K K --> L I -.-> M H -.-> N
The MCP gateway only fires Business Services — it never writes into production
structures. The trace is produced by the production components themselves.
src/
br/
musketeers/
InteropMCP/ Gateway application (13 ObjectScript classes)
InteropMCP/Demo/ Demo production + request/response classes (container demo only)
tests/
br/
musketeers/
InteropMCP/ %UnitTest suites
python/
smoke/ External MCP client smoke harness
docs/
interop-mcp/ Detailed documentation
specs/
001-interop-mcp/ Specification artifacts (spec, plan, contracts, tasks)
| Document | Content |
|---|---|
| Architecture | Component map, request lifecycle, traceability and security models, deployment topology |
| Operations guide | Deploy/teardown, onboarding new Business Services, approval workflow, monitoring, testing |
| API reference | MCP tool contract and ObjectScript class/method reference |
| Troubleshooting | Runbook, UDL dialect rules for this build, diagnostic queries and globals map |
module.xml packages only the gateway (br.musketeers.InteropMCP.PKG). To deploy the application
without the demo, install the module and provision the endpoint in production mode:
Do ##class(br.musketeers.InteropMCP.Setup).Run("prod")
prod mode requires platform authentication and a least-privilege role
(InteropMCPRoles); dev mode (used by the container demo) runs unauthenticated on
localhost only.