AIM1-B01: MCP server scaffold

[MitchellShiell]

A new deployable MCP server (and its client) package is needed that connects to an Arranger instance and exposes its capabilities to any MCP-compatible LLM host. In Aim 1 this is LM Studio; in Aim 2 it will be the purpose-built chat host.

The server needs to support HTTP+SSE transport for LM Studio compatibility. It should validate its connection to Arranger at startup and exit with a descriptive error if the configured catalogues are unreachable. Configuration is entirely via environment variables.

Acceptance Criteria

• Server package exists in the monorepo and starts successfully
• HTTP+SSE Streamable HTTP transport is supported and connectable from LM Studio
• At startup, the server validates each configured catalogue is reachable via the Arranger introspection endpoints and exits with a clear error if not
• Missing required environment variables (ARRANGER_BASE_URL, ARRANGER_CATALOGUES) produce a descriptive startup error
• The list of configured catalogues is surfaced in tool and prompt descriptions so an LLM knows valid options without having to read the catalogue resource first

[justincorrigible]

there is also need to consider the corresponding MCP Client, and this ticket could be the right place for it.
https://modelcontextprotocol.io/docs/develop/build-client

this can always be implemented further as the project moves along, and the server+client duo should be considered two sides to the same coin, rather than separate entities.

[justincorrigible]

Current status from the Arranger branch:

• The MCP package scaffold now exists in the monorepo. i.e. apps/mcp-server
• It has config parsing, an Arranger introspection client, foundation tool definitions, and resource definitions.
• It is not yet a runnable MCP server: SDK bootstrap, transport, registration, and handlers are still pending.

One scope correction: I think Aim 1 should derive the catalogue list from Arranger’s live /introspection response rather than requiring ARRANGER_CATALOGUES as a separate env var. That avoids config drift and matches the current introspection-first design.

Suggested next implementation order:

1. Add MCP SDK bootstrap and transport.
2. Register SQON/catalogue/catalogue-field resources backed by existing Arranger introspection endpoints.
3. Add simple tool handlers for list catalogues / get SQON schema / get catalogue fields.
4. Validate LM Studio compatibility.

note: edited Mitchell's description above, to adjust ARRANGER_BASE_URL as the right variable name.

[mistryrn]

Follow-up from meeting on 2026-05-08: Streamable HTTP is the new standard transport for remote connections, replacing the HTTP+SSE transport.

Reference: https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#streamable-http

Streamable HTTP will be used instead. Backwards compatibility with HTTP+SSE is possible and can be implemented if needed.