AI-Assisted Connexion with MCP
AI-Assisted Connexion with MCP
Connexion v26 includes a Model Context Protocol (MCP) endpoint that allows an AI client to inspect and, when explicitly permitted, drive Connexion through a governed tool interface.
This makes AI useful as an operational and development assistant: it can answer questions about a Connexion instance, inspect channels and devices, analyze status and events, help build or modify channel configurations, and invoke controlled administrative operations.
MCP tooling is primarily designed as a development-box add-on, but under strict conditions it can also be used as a read-only production assistant.
Exposure choices
MCP is disabled until explicitly enabled in standard Connexion installation flows. When enabled, the normal default listener mode is local-only. For developers working with Connexion, a local Connexion instance can be coupled with a locally available LLM to help drive configuration, coding, custom device development etc.
If deployed alongside a production instance, MCP is normally restricted to a read-only feature-set which excludes any message/data access.
Conventional installations default to local-only MCP access. Kubernetes deployments bind MCP to the pod network so it can be reached through cluster networking. External access remains controlled by Kubernetes Services, Gateways, network policies, TLS, and bearer-token authentication.
The Services Options wizard enables the MCP endpoint and selects its listener mode and port. Local and public exposure should only be used on a deliberately controlled network path with HTTPS and bearer-token authentication.
Listener mode | Bind behavior | Intended use |
|---|---|---|
Local only | Binds to 127.0.0.1 | An AI client running on the Connexion host |
Local and public | Binds to 0.0.0.0 | Clients on an explicitly controlled network path |
Explicit address | Binds to a specified host address | A selected interface, VM/host path, or controlled service endpoint |
Profile | Behavior |
|---|---|
Development | Broad inspection and mutation surface; intended for controlled development environments |
Production read-only | Read-only tools |
Production read-only, no messages | Read-only tools with message and message-adjacent content excluded |
Tokens, identity, and audit
MCP credential administration is restricted to Connexion super users. The service enforces this boundary when a bearer token is issued, edited, revoked, or deleted; it is not merely a client-side UI restriction. Ordinary users and authorization groups cannot grant themselves MCP access.
Super users issue an MCP bearer token with a unique audit identity, optional expiry, and one or more authorization groups.
Each token has:
An audit identity identifying the MCP client or automation actor.
A human-readable name or description.
An optional expiry time.
Last-used, revoked, and lifecycle information.
One or more associated authorization groups. Permissions from the selected groups are additive and govern which functions the MCP identity can perform.
The plaintext credential is presented to the operator when it is issued. Tokens can be expired, revoked, or deleted without changing the AI client or the Connexion service account.
Channel start and stop operations performed through MCP appear in the Connexion event log with the MCP source and the bearer token's audit identity.
MCP should be thought of as another governed Connexion user.
What the AI can do
The exact tool list depends on the configured exposure policy, but the v26 MCP surface includes tools for:
Listing and inspecting channels, devices, plugins, repositories, routes, certificates, authorization configuration, and application servers.
Reading operational status, device statistics, queue counts, locks, events, logs, and diagnostics.
Querying messages when message access is allowed.
Creating or modifying channel structure, inserting and removing devices, patching device configuration, and saving channel definitions.
Starting, stopping, pausing, and resuming permitted runtime objects.
Validating selected configuration changes before writing them.
Using the shipped Connexion documentation, recipes, playbooks, and site-authored instructions to guide its work.
Mutating tools use explicit confirmation or validation gates. Inputs and outputs have size limits, and content returned from messages, events, and logs is marked as untrusted data to reduce prompt-injection risk.
Device-specific LLM knowledge
The general Connexion documentation teaches an AI how the platform and MCP tools work. A device's DetailedDescription supplies the device-specific contract: what that plugin does, when to use it, what data it accepts and produces, and exactly how its configuration should be constructed.
This couples the instructions to the implementation that they describe. Built-in and customer-authored devices can ship their own LLM-readable guidance in the same runtime assembly as the device, so the knowledge is installed and versioned with the plugin rather than maintained as a separate prompt or server-side document.
All device developers need to do is include a document in their plugin project and set the DetailedDescriptionResourceName attribute to point to it. The LLM can then understand what the plugin does and reason on it.
[DevicePlugin(
"Acme Sender",
"Sends messages to the Acme service",
DeviceDefinitionFlags.None,
DetailedDescriptionResourceName =
"Acme.Device.AcmeSender.DetailedDescription.md")]
public sealed class AcmeSender : BaseDevice<AcmeSenderConfiguration>
{
// Device implementation
}What the detailed description should teach
A useful device instruction document should describe:
The device's purpose, capabilities, limitations, and appropriate use cases.
Accepted input types, produced output types, and any changes made to the message context.
The persisted configuration shape, including exact property paths, types, defaults, required values, valid ranges, and mutually dependent settings.
Common configuration recipes and compact examples that can be adapted safely.
Runtime behavior such as retries, queuing, acknowledgements, batching, file or network access, and side effects.
Validation and testing steps, expected errors, and operational signals that prove the device is working.
This is more than display help. It gives the LLM an authoritative, version-matched configuration contract and reduces the need to guess property names or reverse-engineer saved devices. Connexion's MCP channel-creation and channel-editing playbooks therefore instruct the AI to retrieve a selected plugin's DetailedDescription before changing its configuration.
The document adds knowledge; it does not add authority. MCP exposure policy, token authorization, confirmation gates, validation, audit identity, and the user's requested scope continue to govern what the AI may inspect or change.
Teach the AI your environment
Device DetailedDescription documents teach an LLM how individual plugins work. Connexion v26 also lets administrators teach the LLM site-specific rules, playbooks, and domain knowledge through two purpose-built Global Setting types in the Globals UI.
Global type | Best for | How the LLM receives it |
|---|---|---|
LLM Instruction ( | Focused operating rules, local conventions, and playbooks that should guide the AI's behavior. Instructions can be scoped to the system, a group, or a tab. | Connexion's startup guidance tells the LLM to load these instructions when a session begins. System instructions apply globally; matching group and tab instructions are also attached automatically as |
LLM Document ( | Longer Markdown or text knowledge such as custom workflows, vendor file formats, message conversions, custom data types, site routing conventions, or documentation for a customer-authored plugin. | Each document includes a summary plus optional tags, scenarios, and applicable plugin class names. Connexion automatically surfaces matching summaries as |
How context is delivered
The built-in Connexion MCP server instructions are supplied during MCP initialization. User-authored knowledge then joins the working context in two stages:
At session startup, the built-in instructions direct the LLM to call
GetMcpInstructions, loading the administrator-authored operating guidance for that Connexion instance.As the LLM explores a group, channel, or device, Connexion automatically adds the instructions and document summaries relevant to that scope. System-scoped content is always eligible; group and tab content follows the channel hierarchy, and plugin-specific document matches are prioritized.
The full body of every knowledge document is not forced into the initial prompt. Connexion supplies compact discovery metadata first and lets the LLM retrieve the relevant document with GetMcpDocument or find it with SearchMcpDocuments. This keeps the context focused while still making local knowledge discoverable.
Example: teaching local channel conventions
An administrator can create an LLM Document describing the site's channel naming rules, queue placement, retry strategy, routing conventions, and known legacy patterns to avoid. A matching LLM Instruction can state that these conventions must be consulted before creating or editing channels. Together they let the organization extend Connexion's built-in guidance without changing the MCP server or maintaining a separate AI prompt.
Connect Claude Code to Connexion
Add a .mcp.json file to the project opened by Claude Code:
{
"mcpServers": {
"connexion": {
"type": "http",
"url": "https://localhost:5100/",
"headers": {
"Authorization": "Bearer ${CONNEXION_MCP_TOKEN}"
}
}
}
}Store the issued bearer token in the CONNEXION_MCP_TOKEN environment variable in the environment from which Claude Code is launched. Claude Code automatically expands ${CONNEXION_MCP_TOKEN} when it reads the MCP configuration, so the token does not need to be written into .mcp.json or committed to source control.
For the current PowerShell session:
$env:CONNEXION_MCP_TOKEN = "<issued bearer token>"For macOS or Linux:
export CONNEXION_MCP_TOKEN="<issued bearer token>"After setting the variable, start Claude Code from that environment. The example uses Connexion's local HTTPS endpoint; change the URL only when the MCP exposure policy has been deliberately configured for network access.
MCP Usage
The current MCP tools can materially assist device and channel development. An AI can inspect installed plugin metadata, add a device to a channel, patch its configuration, validate and save channel structure, query events and logs, and compare runtime status with the intended design.
Example: ask for operational status
Asked only for the status of the local development instance, Claude used Connexion MCP tools to check server health, channel activity, listener exposure, recent logs, plugin availability, and alerting configuration, then highlighted the findings worth investigating.
Example: create and verify an HL7 integration
Claude Code was given a compact description of the desired integration rather than a device-by-device implementation plan:
Build and verify an HL7 channel in my local dev Connexion via MCP.
CHANNEL: "AI HL7 Enrichment Demo" in a tab named "AI Demo" under Default Group.
REQUIREMENTS
- Accept HL7 v2 over MLLP on port 2575, return ACKs.
- Set MSH-4.1 to CNXN.
- Append a ZZZ segment; set ZZZ-3.1 to now as yyyyMMddHHmmss.
- Send to MLLP localhost:12000.
Run a few synthetic HL7 messages through the channel and verify the changes are as expected.Claude created a new tab and new channel with the configured devices. It then started the channel, sent through sample messages and observed the results both via temporary mllp receiver and the queue’s processing history.
Example: extend Connexion with ASTM support
An accelerated split-screen run showing Claude Code create, compile, and verify an ASTM-to-HL7 integration in Connexion via MCP.
The assistant validates the result with an ASTM simulator across single-message, multi-frame, bad-checksum, and timeout scenarios. Three messages are converted and delivered as ORU^R01 messages, while the incomplete timed-out session is discarded as expected. The example demonstrates that MCP can do more than configure existing devices: an LLM can use Connexion's Custom Code devices to introduce new integration behavior, compile it, exercise it, diagnose edge cases, and leave a reusable channel behind.
Example: Create Compiled Devices
LLM-created compiled devices from the ASTM example above. The LLM took the custom code devices, created Visual Studio projects, compiled the projects and imported the plugins into Connexion - including creating some basic UIs for each device.