Loomscope

ADR-0005: An MCP server for AI agents

Edit this page

Status: Proposed Date: 2026-08-14

Context

Loomscope already has an AI assistant: a chat page backed by the Vercel AI SDK with ten read-only inventory tools, a provider abstraction over Anthropic, OpenAI and Ollama, and a per-organisation token budget.

It has a structural limit. The assistant only exists inside Loomscope's own UI. The questions people actually want to ask cross tools:

"This alert names 10.4.2.19. What is it, what does it run, is it exposed, and what changed on it this week?"

That question arrives in an incident channel, an IDE, or a terminal — not in Loomscope's chat page. Answering it means the person leaves their context, opens Loomscope, asks, and carries the answer back.

The Model Context Protocol is the emerging standard for exposing tools and data to AI agents, and the work is largely already done: server/ai/tools/ contains inventory tools written against org-scoped queries. The gap is protocol, not capability.

Decision

Ship a Loomscope MCP server exposing the inventory as tools and resources to any MCP-capable client, built on the public REST API (ADR-0003).

Transport. Both. stdio for local clients — a desktop AI application or an editor launching the binary directly — and streamable HTTP for remote clients, served by the control plane so a whole team shares one endpoint.

Tools exposed (initially read-only): find a host by IP, hostname or MAC; list services on a host; search services by signature or version; query vulnerabilities by severity, host or state; look up certificates and their expiry; describe a site; diff two snapshots; summarise a topology view.

Resources, addressed by URI, so an agent can reference a host in a conversation without re-querying: loomscope://host/{id}, loomscope://site/{code}, loomscope://snapshot/{id}.

Authorisation. An MCP session authenticates with an API key and inherits exactly that key's organisation and scopes. Row-level security applies unchanged. The MCP server can never see more than the key it was given.

Read-only in the first release. Write tools — acknowledging a vulnerability, triggering a scan — are deliberately deferred. Handing an agent the ability to launch network scans deserves its own decision, with an explicit human-confirmation design.

No model runs here. This is the inverse of the existing assistant: the assistant calls a model from Loomscope, while the MCP server exposes Loomscope to somebody else's model. It has no provider configuration, no token budget and no API cost, because it never calls an LLM.

Alternatives considered

Extend the built-in assistant instead. Rejected as a substitute. Making the in-app assistant better does not help anyone whose question arises somewhere else. The two are complementary, and the MCP server is the cheaper of the two to build because the tools already exist.

Expose the REST API and let people write their own integrations. Rejected as sufficient. It is true that any capable agent can call HTTP given an OpenAPI document, but MCP standardises discovery, argument schemas and result shaping — which is what makes an agent reliable rather than merely capable.

Wait for MCP to settle. Considered. The protocol is young and will move. The mitigation is that the server is a thin adapter over the REST API: if MCP changes, we rewrite the adapter, not the inventory logic. That containment is the main reason ADR-0003 comes first.

Make it write-capable immediately. Rejected. An agent that can start scans is an agent that can generate network traffic across a customer's estate on a misread instruction. Read-only first, and writes only behind explicit confirmation.

Consequences

Accepted costs.

  • MCP is a moving specification; expect churn for at least a year.
  • A new authenticated network surface, which is a security surface. It needs its own tests and its own section in the threat model.
  • Users will reasonably expect write tools, and we will be saying no at first.
  • Support questions will arrive about third-party MCP clients we do not control.

Gains.

  • Loomscope's inventory reaches the tools people already work in, instead of requiring them to come to Loomscope.
  • Incident response gets materially faster: the inventory answer arrives in the channel where the incident is being handled.
  • It is a genuine differentiator. Very few self-hosted inventory tools are agent-addressable, and this is a strong fit for a product whose whole point is knowing what is on the network.
  • Reuses the existing tool implementations almost directly.

Privacy note that must stay true. Exposing Loomscope over MCP means an external model may receive inventory data. That is the operator's choice to make, so the MCP server ships disabled by default, and its documentation states plainly what leaves the network when it is switched on. This does not weaken the no-telemetry commitment: Loomscope still sends nothing on its own.