MCP server

Mildport ships a Model Context Protocol server, so an agent can do what the widget does: look at a file, propose a mapping, ask about the parts it isn’t sure of, and apply the import. Same engine, same license key, same entitlements — the agent is simply another caller.

Nothing about this weakens the boundary. The MCP surface runs inside your deployment, files stay where they already are, and every call is checked against the same license the widget uses.

Two transports

HTTP — for hosted and networked agents. One stateless endpoint:

POST /api/import/v1/mcp
Authorization: Bearer <your license key>

Every request is self-contained: no sessions, no SSE stream, plain JSON responses. Point any MCP client that speaks streamable HTTP at that URL.

stdio — for desktop clients that spawn a subprocess (Claude Desktop, editors, local agents):

IMPORT_LICENSE_KEY=<your license key> \
MONGO_CONNECTION_STRING=mongodb://host:27017/cap_import \
  pnpm run import:mcp-stdio

The license is verified once at startup rather than per call — a stdio process has exactly one caller for its whole life.

stdio runs from the build, not from source

It boots the full engine, which needs compiled decorator metadata. Run pnpm build first, or use the shipped image, where dist/ is already there. Also: stdout is the JSON-RPC wire — every log and diagnostic goes to stderr, so nothing corrupts the protocol.

What the agent can do

Tool	What it does
analyze_file	Read a file and describe its structure
list_catalogs	The target catalogs available to this tenant
propose_mapping · resolved_mapping	Suggest a column mapping, then read back the resolved one
dry_run_transform	Preview a transform without touching data
resolved_references	Inspect how references resolved
execute_import	Apply the import
list_questions · answer_question · dismiss_question	Work the ambiguity ledger — the parts the engine flagged
list_changesets · get_changeset · revert_changeset	Inspect and undo staged applies

The read tools work on any license. The write surface — an agent answering ambiguity questions on your behalf — is gated by the agentAccess entitlement, which is Enterprise and off by default, including on existing Enterprise keys. A new machine-write capability has to be opted into deliberately, never inherited by a key you already hold.

Why the ambiguity ledger matters here

An agent that guesses silently is worse than no agent. When the engine is unsure — an ambiguous column, a value that could be two things — it records a question instead of picking. Your agent can list those questions, answer the ones it genuinely knows, and leave the rest for a human.

That is the difference between an import you can explain afterwards and one you cannot.

Configure a desktop client

Most MCP clients take a command and an environment block. For the stdio transport:

{
  "mcpServers": {
    "mildport": {
      "command": "node",
      "args": ["dist/cli/mcp-stdio.js"],
      "env": {
        "IMPORT_LICENSE_KEY": "<your license key>",
        "MONGO_CONNECTION_STRING": "mongodb://host:27017/cap_import"
      }
    }
  }
}

Run it from your Mildport checkout or image directory. For a hosted engine, use the HTTP endpoint with an Authorization header instead — no local process required.

Next: Webhooks · Configuration reference