Image-gen MCP Connector

TL;DR

Add the gateway's image-gen MCP server as a regular row in Settings → Connectors, authenticated by the user's CoreSpeed JWT through the existing local credential broker — the same path X already uses. The only behavioral divergence from X is that image-gen needs no per-provider OAuth dance (a CoreSpeed identity is the credential), encoded structurally by omitting connectURL from the catalog entry. Inline base64 images render directly in the tool-call view and in agent markdown — no disk caching, no broker response transform, no new settings tab.

Why we're doing this

1. Image generation belongs alongside other gateway tools. Linear, Notion, X, Apify all live in connector-catalog.json and surface through one consistent UI. Image-gen is just another gateway MCP — making it a connector row keeps the mental model intact.
2. The closed PR over-rotated on a non-problem. Converting inline base64 to disk files (the InlineImageCache path) added 455 LOC of file lifecycle plus markdown-sanitizer cleanup just to avoid putting base64 in the rendered text. Direct base64 decode into NSImage at render time avoids the file lifecycle entirely.
3. JWT auth + broker refresh already exists. The X connector demonstrated the full pattern: localhost broker route, X-Broker-Auth gating, JWT injection, 401-retry, automatic token refresh. Image-gen needs zero new auth machinery.
4. Path convention is moving. The gateway is deprecating /<id>/mcp in favor of /mcp/<id>. Image-gen ships at /mcp/image-gen from day one. Deriving the broker prefix from mcpURL.path lets the catalog URL own the convention; X migrates later with a one-line catalog change.

Before / After at a glance

Settings → Connectors (new row)

Image-gen lives in the existing connector list. The row behavior depends on CoreSpeed sign-in state and on whether the catalog entry carries a connectURL.

Auth flow — same broker pattern as X

Agents talk to 127.0.0.1, not to gateway.ai.corespeed.io. The broker rewrites the request, injects a fresh JWT, and forwards it. Refresh and 401-retry are transparent to the agent.

The mapping inside the broker is unchanged: 127.0.0.1:PORT/<pathPrefix><suffix> → <upstreamBase><suffix>. With pathPrefix derived from mcpURL.path, prefix and upstream-path agree by construction, so the suffix forwards cleanly even when query strings or future sub-paths appear.

Path convention — derive from mcpURL.path

Today's hardcoded "/\(entry.id)/mcp" only works because every .corespeed connector happens to mount at /<id>/mcp upstream. Image-gen breaks that assumption: it ships at /mcp/image-gen. Promote the catalog URL to source of truth.

BrokerRoute(
  pathPrefix: "/\(entry.id)/mcp",    // hardcoded
  upstreamBase: entry.mcpURL,
  injection: .coreSpeedJwt,
  ...
)

// X:        /x/mcp           → gateway/x/mcp           ✓
// image-gen /image-gen/mcp   → gateway/mcp/image-gen   ✗

BrokerRoute(
  pathPrefix: entry.mcpURL.path,        // catalog-driven
  upstreamBase: entry.mcpURL,
  injection: .coreSpeedJwt,
  ...
)

// X:        /x/mcp           → gateway/x/mcp           ✓
// image-gen /mcp/image-gen   → gateway/mcp/image-gen   ✓
// X migration later: change mcpURL only.

ConnectorStore.coreSpeedConfigForSession matches: the localhost URL it emits becomes http://127.0.0.1:\(port)\(entry.mcpURL.path) instead of .../\(entry.id)/mcp. Skip any .corespeed entry whose mcpURL.path is empty or "/" so a malformed catalog can never produce a route that matches every request.

Key code snippets

Catalog entry

{
  "id": "image-gen",
  "displayName": "Image generation",
  "description": "Generate and edit images. Charged per request.",
  "iconAsset": "mcp-image-gen",
  "mcpURL": "https://gateway.ai.corespeed.io/mcp/image-gen",
  "auth": "corespeed"
}

No connectURL — absence is the structural signal that this connector skips the per-provider OAuth dance. Staging URL substitution is already handled generically by ConnectorCatalog.loadFromBundle().

New optional field: description. ConnectorCatalogEntry gains an optional description: String?. ConnectorTile renders it as a second sub-line below the existing name+cred line, never replacing the auth-method label. Image-gen uses this slot to surface the cost model explicitly ("Charged per request") so the user knows why the Disconnect button matters. Other catalog entries (X, Linear, …) leave description nil; their rows stay single-line and unchanged.

ConnectorStore — per-id boolean + one early-return per call site

// Per-id UserDefaults boolean. Idiomatic, KVO-friendly.
private static let disabledKeyPrefix = "connector."   // suffix: ".disabled"

func isDisabled(id: String) -> Bool {
  UserDefaults.standard.bool(forKey: "\(Self.disabledKeyPrefix)\(id).disabled")
}

func setDisabled(id: String, _ disabled: Bool) {
  UserDefaults.standard.set(disabled, forKey: "\(Self.disabledKeyPrefix)\(id).disabled")
  onStateChanged.fire()
}

// hydrate() — one ternary, every .corespeed entry
case .corespeed:
  let locallyDisabled = isDisabled(id: entry.id)
  if entry.connectURL == nil {
    statuses[entry.id] = (account.isSignedIn && !locallyDisabled)
      ? .connected(expiresAt: nil)
      : .disconnected
  } else {
    statuses[entry.id] = .disconnected   // reconciled async
  }

// connect(id:) — clear flag, early-return for local-only
setDisabled(id: id, false)
guard entry.connectURL != nil else {
  statuses[id] = account.isSignedIn ? .connected(expiresAt: nil) : .disconnected
  return
}
// existing OAuth dance below for entries with connectURL

// disconnect(id:) — set flag, early-return for local-only
setDisabled(id: id, true)
statuses[id] = .disconnected
guard entry.connectURL != nil else { return }
// existing server-side DELETE below

Reactive status from sign-in

// In ConnectorStore.init, after hydrate():
account.onSignInStateChanged = { [weak self] in
  guard let self else { return }
  for entry in self.catalog.connectors
    where entry.auth == .corespeed && entry.connectURL == nil {
    self.statuses[entry.id] = account.isSignedIn
      ? .connected(expiresAt: nil)
      : .disconnected
  }
}

Broker URLSession timeout bump

private static let upstreamSession: URLSession = {
  let config = URLSessionConfiguration.default
  config.timeoutIntervalForRequest  = 300   // 5 min per-chunk idle
  config.timeoutIntervalForResource = 600   // 10 min total wall-clock
  return URLSession(configuration: config)
}()

Replaces every URLSession.shared.data(for:) call inside the broker's .coreSpeedJwt path. Fast routes (X) are unaffected — bumped timeouts just delay failure detection on the slow tail.

Image rendering surfaces

MarkdownSanitizer — allow data: URIs

The sanitizer currently strips every image to prevent untrusted markdown from issuing tracking-pixel / exfiltration requests. Loosen the predicate to inline data:image/... URIs only — they carry their bytes inline and make zero network requests. HTTPS images stay stripped (preserves the original security guarantee).

mutating func visitImage(_ image: Image) -> Markup? {
  guard let source = image.source,
        source.hasPrefix("data:image/") else {
    return nil
  }
  return image
}

ToolCallView — render .image ContentBlocks

Agents typically don't re-emit multi-megabyte base64 inline. The primary surface where users see generated images is the tool-call result panel. Today's toolCallContentView only handles .text; add an .image branch:

case .content(let block):
  if case .text(let t) = block {
    // existing
  } else if case .image(let img) = block {
    if let data = Data(base64Encoded: img.data),
       let nsImage = NSImage(data: data) {
      Image(nsImage: nsImage)
        .resizable()
        .scaledToFit()
        .frame(maxHeight: 400)
        .cornerRadius(8)
    }
  }

No InlineImageCache, no disk writes, no broker response transform. NSImage(data:) decodes PNG / JPEG / WebP / GIF natively on macOS 15+. The base64 stays in memory for the message's lifetime; SwiftUI caches the rendered image.

Acceptance criteria

1. Image-gen appears in Settings → Connectors

   With the placeholder icon and displayName "Image generation".

2. Signed in + enabled (default) shows "Connected" + Disconnect

   Status dot is green. Disconnect button visible.

3. Disconnect is a local opt-out, no network

   Clicking Disconnect flips the connectors.locallyDisabled UserDefaults flag, row transitions to "Disconnected" + Connect. No browser, no DELETE call. Re-clicking Connect clears the flag immediately.

4. Signed-out row shows "Sign in to CoreSpeed"

   Both buttons suppressed. Status dot gray. The local-disable flag persists across the signed-out window and is honored on next sign-in.

5. Session spawn honors enabled state

   With image-gen enabled, MCPServerConfig URL is http://127.0.0.1:<brokerPort>/mcp/image-gen + X-Broker-Auth. With image-gen locally disabled, no config is emitted. X still produces .../x/mcp — both derived from mcpURL.path.

6. generate_image succeeds end-to-end

   Agent invokes the tool; broker injects JWT; gateway validates and forwards; agent receives application/json with inline base64.

7. Generated image renders inline in the tool-call view

   At a reasonable max-height (~400pt), scaled-to-fit, with corner radius.

8. Markdown data: images render

   If the agent emits ![](data:image/png;base64,...) in its response text, the renderer displays it.

9. HTTPS images stay stripped

   If the agent emits https://...png markdown, the renderer still drops it — preserving the original security guarantee.

10. JWT expiry mid-call is transparent

    A 401 during a long image-gen call triggers the broker's existing refresh-and-retry path. The agent sees a successful response.

11. Sign-out flips status reactively

    Without restarting Sarea. The row transitions to "Sign in to CoreSpeed" within one observation tick.

Scope estimate

Non-goals & risks

Non-goals

• No base64 → file conversion. The agent gets bytes inline; the UI decodes once at render time. Disk caching, file lifecycle, sandbox path scoping — all outside scope.
• No new "Built-in Tools" tab. Image-gen is a connector row, not a new product surface. We're not designing a separate Tools concept that would compete with connectors.
• No new InjectionPolicy case. .coreSpeedJwt already does exactly what image-gen needs. A .gatewayApiKey case would introduce two parallel auth paths for one credential domain.
• No SSE / streaming MCP transport. Image-gen returns application/json; the existing buffered path is correct. SSE adoption is a separate, broker-wide change.
• No HTTPS image allowlist (v1). Only data: URIs render. If a future feature needs hosted-image rendering from gateway.ai.corespeed.io, the sanitizer predicate gains one line; not building the allowlist prophylactically.
• No live-session token swap. Subprocess env is frozen at spawn; JWT rotation only affects new sessions. The broker handles refresh transparently per-request — this is already a property of the broker design.

Risks