insika 0.2.0 → 0.7.0

data/lib/insika/knowledge_store.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "time"
+
+module Insika
+  # LEARNED concepts, one per agent (+ optional tenant). Holds the complete
+  # concept markdown (frontmatter + body) in the durable Store, the same
+  # content/updated_at/bounded-history record shape `SkillStore` uses for
+  # SKILL.md — so the Studio's editor and undo work identically.
+  #
+  # Scoped like `MemoryStore` (agent/tenant baked into the scope string, not a
+  # second constructor argument): a concept is engine-written, per-deployment
+  # knowledge, never shared across agents the way a skill can be.
+  #
+  #   scope: "knowledge:<agent_id>"              # default
+  #   scope: "knowledge:<agent_id>:<tenant>"      # explicit tenant (multi-merchant)
+  #   key:   "concept:<name>"
+  #
+  # Record shape, one per concept:
+  #   { "content" => "<entire concept markdown>", "updated_at" => iso8601,
+  #     "history" => [ { "content" =>, "at" => }, ... ] }
+  #
+  # Layer 1 only: this is a plain upsert (last-write-wins, old version pushed
+  # into history). Dedup/merge/conflict detection across sightings is layer 2,
+  # not this store's job.
+  class KnowledgeStore
+    SCOPE_PREFIX = "knowledge"
+    KEY_PREFIX = "concept:"
+    HISTORY_MAX = 20
+
+    def initialize(store:)
+      @store = store
+    end
+
+    # -> String | nil (the complete concept markdown).
+    def get(agent_id, name, tenant: nil)
+      record(agent_id, name, tenant)&.fetch("content", nil)
+    end
+
+    # -> {"content" =>, "updated_at" =>} | nil. Cheap by design (no YAML
+    # frontmatter parse) — `updated_at` is the raw record's OWN timestamp,
+    # written on every upsert, so a caller can use it as a memoization key
+    # (Index::Scan's read cache) without re-parsing content that has not
+    # changed since the last read.
+    def meta(agent_id, name, tenant: nil)
+      rec = record(agent_id, name, tenant)
+      rec && { "content" => rec["content"], "updated_at" => rec["updated_at"] }
+    end
+
+    # -> [String] concept names for the scope, lexicographic order.
+    def names(agent_id, tenant: nil)
+      @store.list(scope_for(agent_id, tenant), KEY_PREFIX).map { |k| k.delete_prefix(KEY_PREFIX) }
+    end
+
+    # -> { name => content } of every concept in the scope.
+    def all(agent_id, tenant: nil)
+      names(agent_id, tenant: tenant).each_with_object({}) { |n, acc| acc[n] = get(agent_id, n, tenant: tenant) }
+    end
+
+    # Upsert. -> Hash (the stored record).
+    def write(agent_id, name, content, tenant: nil)
+      key = name.to_s
+      current = record(agent_id, key, tenant)
+      rec = build_record(content.to_s, current)
+      @store.set(scope_for(agent_id, tenant), KEY_PREFIX + key, rec)
+      rec
+    end
+
+    # -> bool (did it exist?).
+    def delete(agent_id, name, tenant: nil)
+      @store.delete(scope_for(agent_id, tenant), KEY_PREFIX + name.to_s)
+    end
+
+    # -> [ { "content" =>, "at" => } ] most recent first.
+    def versions(agent_id, name, tenant: nil)
+      record(agent_id, name, tenant)&.fetch("history", []) || []
+    end
+
+    # Restores version `index` as the current content (a new write). -> Hash.
+    def restore(agent_id, name, index, tenant: nil)
+      hist = versions(agent_id, name, tenant: tenant)
+      i = Integer(index)
+      raise Insika::NotFoundError, "concept '#{name}' not found" unless record(agent_id, name.to_s, tenant)
+      raise Insika::ValidationError, "version #{index} does not exist" if i.negative? || i >= hist.length
+
+      write(agent_id, name, hist[i]["content"], tenant: tenant)
+    end
+
+    # Writes one `<dir>/<name>.md` per concept — the storage format IS the
+    # export format, so this is a dump, not a converter: each file is the
+    # concept's content, byte for byte, directly consumable by okf-gem
+    # (`OKF::Bundle`) or graphify. Unlike a lossy re-serialization (YAML.dump
+    # on a curated corpus, say), re-exporting the same store is idempotent —
+    # no `force` guard needed, there is nothing here to lose. -> [paths].
+    def export_dir(agent_id, dir, tenant: nil)
+      FileUtils.mkdir_p(dir)
+      names(agent_id, tenant: tenant).map do |name|
+        path = File.join(dir, "#{name}.md")
+        File.write(path, get(agent_id, name, tenant: tenant))
+        path
+      end
+    end
+
+    # -> String (one GraphML document — the whole scope as a graph, §5's
+    # follow-up export shape). A record that fails to parse (a hand edit
+    # gone wrong) is skipped rather than breaking the whole export.
+    def export_graphml(agent_id, tenant: nil)
+      concepts = names(agent_id, tenant: tenant).filter_map do |name|
+        Knowledge::Concept.parse(get(agent_id, name, tenant: tenant))
+      end
+      Knowledge::GraphmlExport.build(concepts)
+    end
+
+    private
+
+    def scope_for(agent_id, tenant)
+      t = Coercion.presence(tenant)
+      t ? "#{SCOPE_PREFIX}:#{agent_id}:#{t}" : "#{SCOPE_PREFIX}:#{agent_id}"
+    end
+
+    def record(agent_id, name, tenant)
+      @store.get(scope_for(agent_id, tenant), KEY_PREFIX + name.to_s)
+    end
+
+    def build_record(content, current)
+      history = current ? current.fetch("history", []) : []
+      if current
+        history = [{ "content" => current["content"], "at" => current["updated_at"] }] + history
+        history = history.first(HISTORY_MAX)
+      end
+      # Microsecond precision ON PURPOSE (MemoryStore's own rule): `updated_at`
+      # is Index::Scan's cache-invalidation key — second precision collides
+      # for two writes in the same second (a backfill, a rapid consolidation),
+      # and a collision there means a stale cached concept survives a real
+      # write until the next search that lands in a different second.
+      { "content" => content, "updated_at" => Time.now.utc.iso8601(6), "history" => history }
+    end
+  end
+end

data/lib/insika/mcp_client.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Insika
+  # Builds a live MCP client for an McpStore record. The ONE seam
+  # between Insika and the transport gem: `ruby_llm-mcp` speaks stdio,
+  # Streamable HTTP and SSE with the full lifecycle (initialize handshake,
+  # session-id, notifications) — Insika stops maintaining its own protocol
+  # client. Swapping the gem later (e.g. to modelcontextprotocol/ruby-sdk)
+  # touches only this file.
+  #
+  # `require "ruby_llm/mcp"` is LAZY, done here rather than at `require
+  # "insika"` time (spec/insika/load_guard_spec.rb): the gem drags in
+  # ruby_llm + httpx, the same opt-in-cost discipline as every other provider
+  # surface.
+  #
+  # Client LIFECYCLE (start/stop, registering the child process with
+  # Insika::Shutdown so it dies on SIGTERM) belongs to whoever holds the
+  # client across calls — the live tool registry, later work. `for` itself
+  # returns an unstarted client (`start: false`); building one is cheap and
+  # side-effect-free.
+  module McpClient
+    # A stdio instance is arbitrary command execution by config — refused
+    # unless the operator opted in (config-over-convention, same pattern as
+    # the egress envs).
+    class StdioDisabled < Insika::Error; end
+
+    module_function
+
+    # `record` — the RAW McpStore record (get_raw/all_raw; never the masked
+    # one — a masked record's credentials are the __OCULTO__ sentinel, not
+    # something a client can connect with).
+    # -> RubyLLM::MCP::Client, not started. Raises StdioDisabled (stdio, gate
+    # off), Insika::Error (http/sse, egress-blocked url) or
+    # Insika::ValidationError (unknown transport).
+    def for(record, env_reader: Insika::EnvSchema, egress: Insika::EgressGuard)
+      require "ruby_llm/mcp"
+      apply_origin_header_fix!
+
+      case record["transport"].to_s
+      when "stdio" then stdio_client(record, env_reader: env_reader)
+      when "http" then http_client(record, :streamable_http, egress: egress)
+      when "sse" then http_client(record, :sse, egress: egress)
+      else
+        raise Insika::ValidationError,
+              "MCP instance '#{record["name"]}' has an unknown transport: #{record["transport"].inspect}"
+      end
+    end
+
+    def stdio_client(record, env_reader:)
+      unless env_reader.truthy?(env_reader.read("INSIKA_MCP_STDIO"))
+        raise StdioDisabled,
+              "MCP instance '#{record["name"]}' is stdio (arbitrary command execution by config) — " \
+              "set INSIKA_MCP_STDIO=1 to allow it to start"
+      end
+
+      RubyLLM::MCP.client(
+        name: record["name"], transport_type: :stdio, start: false,
+        config: { command: record["command"], args: Array(record["args"]), env: record["env"] || {} }
+      )
+    end
+
+    def http_client(record, transport_type, egress:)
+      url = record["url"]
+      reason = egress.violation(url)
+      raise Insika::Error, "MCP target blocked: #{reason}" if reason
+
+      RubyLLM::MCP.client(
+        name: record["name"], transport_type: transport_type, start: false,
+        config: { url: url, headers: record["headers"] || {} }
+      )
+    end
+
+    # https://github.com/patvice/ruby_llm-mcp/issues/140 (open, unfixed as of
+    # 1.0.1): StreamableHTTP#build_common_headers sets `Origin` to the MCP
+    # endpoint's OWN url (path included) on every request. That's invalid per
+    # RFC 6454 §7 (Origin is scheme+host[+port], never a path) and unneeded —
+    # a server-to-server client has no browser Origin to report, and the
+    # reference TS/Python SDKs never send one. No allowlist can ever match a
+    # value that carries a path, so any server enforcing the spec's
+    # DNS-rebinding Origin check (GitHub's remote MCP, Grafana, Metabase, ...)
+    # rejects every request. Same prepend the issue's own author ships in
+    # production. `Module#prepend` no-ops if the module is already in the
+    # ancestor chain, so calling this on every `for` is cheap and safe.
+    def apply_origin_header_fix!
+      RubyLLM::MCP::Native::Transports::StreamableHTTP.prepend(OriginHeaderFix)
+    end
+
+    module OriginHeaderFix
+      def build_common_headers
+        super.except("Origin")
+      end
+    end
+  end
+end

data/lib/insika/mcp_json.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Insika
+  # The de-facto `mcpServers` JSON format every MCP client (Claude Desktop,
+  # Cursor, ...) already uses — one parser shared by all three PR3 config
+  # surfaces (CLI `insika mcp import`, the API `/v1/mcp` PUT, Studio's "Import
+  # JSON" textarea).
+  #
+  #   {
+  #     "mcpServers": {
+  #       "tavily":     { "url": "https://mcp.tavily.com/mcp", "headers": {...} },
+  #       "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"] }
+  #     }
+  #   }
+  #
+  # A server entry with `command` and no `url` is stdio; one with `url` and no
+  # `command` is `http` (Streamable HTTP, the modern default) unless it names
+  # `"transport": "sse"` explicitly — the bare format has no other way to spell
+  # SSE. `export` always writes `transport` back so a round-trip is lossless.
+  module McpJson
+    module_function
+
+    # `json` — a JSON string or an already-parsed Hash (either key type).
+    # Upserts every entry via `mcp_store` (per-key secret reconciliation, same
+    # as any other upsert — re-importing an export's `__OCULTO__` sentinel
+    # preserves whatever is already stored, never wipes it).
+    # -> [Hash] the masked upserted records, in the document's key order.
+    def import(json, mcp_store:)
+      data = json.is_a?(String) ? JSON.parse(json) : stringify(json)
+      servers = stringify(data["mcpServers"] || {})
+      servers.map { |name, cfg| mcp_store.upsert(attrs_from(name, stringify(cfg))) }
+    end
+
+    # -> { "mcpServers" => { name => {...} } }, secrets masked (never plaintext
+    # — `mcp_store.all` already masks, this only reshapes).
+    def export(mcp_store:)
+      { "mcpServers" => mcp_store.all.each_with_object({}) { |record, acc| acc[record["name"]] = server_from(record) } }
+    end
+
+    def attrs_from(name, cfg)
+      {
+        name: name.to_s,
+        transport: presence(cfg["transport"]) || (presence(cfg["command"]) ? "stdio" : "http"),
+        command: cfg["command"], args: cfg["args"], url: cfg["url"],
+        headers: cfg["headers"], env: cfg["env"],
+        description: cfg["description"], enabled: cfg.fetch("enabled", true)
+      }
+    end
+    private_class_method :attrs_from
+
+    def server_from(record)
+      body = record["transport"] == "stdio" ? { "command" => record["command"], "args" => record["args"], "env" => record["env"] }
+                                             : { "url" => record["url"], "headers" => record["headers"] }
+      body.merge(
+        "transport" => record["transport"],
+        "description" => record["description"],
+        "enabled" => record["enabled"]
+      ).compact
+    end
+    private_class_method :server_from
+
+    def stringify(obj)
+      return {} unless obj.is_a?(Hash)
+
+      obj.each_with_object({}) { |(k, v), acc| acc[k.to_s] = v }
+    end
+    private_class_method :stringify
+
+    def presence(value) = Insika::Coercion.presence(value)
+    private_class_method :presence
+  end
+end

data/lib/insika/mcp_live_tool.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+
+module Insika
+  # One live MCP tool. `name`/`description`/`params_schema`
+  # come from the CACHED descriptor (McpStore#tools_cache — no I/O to build
+  # this instance, same cost as any other tool the registry hands out).
+  # `#execute` is the only thing that touches the network, calling through
+  # `client_for` (Insika::McpToolRegistry's memoized, started client — this
+  # class never builds or starts one itself) into the gem's own
+  # `RubyLLM::MCP::Tool#execute`, which already unwraps `content[].text` and
+  # turns `isError` into `{error:}`.
+  #
+  # Like every tool in this codebase, `#execute` NEVER raises: a connection
+  # or protocol failure becomes `{error:}`, the model's normal failure path
+  # (see Tools::DataDefinedTool's own rule).
+  class McpLiveTool < RubyLLM::Tool
+    def initialize(instance_name:, tool:, client_for:)
+      @instance_name = instance_name
+      @tool = tool
+      @client_for = client_for
+      super()
+    end
+
+    def name = @tool["name"]
+    def description = @tool["description"].to_s
+
+    def params_schema
+      schema = @tool["inputSchema"]
+      schema.nil? || schema.empty? ? { "type" => "object", "properties" => {} } : schema
+    end
+
+    def execute(**params)
+      live = @client_for.call.tool(@tool["name"])
+      raise Insika::NotFoundError, "tool '#{@tool["name"]}' no longer offered" if live.nil?
+
+      live.execute(**params)
+    rescue StandardError => e
+      { error: "MCP instance '#{@instance_name}' tool '#{@tool["name"]}' failed: #{e.message}" }
+    end
+  end
+end

data/lib/insika/mcp_store.rb

@@ -3,19 +3,27 @@
 module Insika
   # MCP instances authored at runtime. One
   # record per instance in the ConfigStore (scope "mcp"), keyed by the name slug
-  # (`tavily`, `github`, ...). Holds transport/command/url, the `enabled` flag and
-  # a Hash of `env` credentials (tokens/keys the instance injects into the server).
+  # (`tavily`, `github`, ...). Holds transport/command/args/url, the `enabled`
+  # flag, and two credential Hashes: `env` (stdio child-process environment) and
+  # `headers` (http/sse request headers). `env` used to double as
+  # "HTTP headers" for http/sse instances; a record written under that old
+  # meaning is migrated ON READ (see `migrate_legacy_headers!`), never rewritten
+  # silently (`insika doctor` flags it so the operator re-saves it explicitly).
   #
-  # The credentials (`env`) NEVER leave here in plaintext to the UI: the display
-  # reads (`get`/`all`) mask EACH value with the `__OCULTO__` sentinel. Only
-  # `get_raw`/`all_raw` (consumed by an MCP client, never by the screen) return
-  # the real values. On write, the sentinel coming back preserves the value; a new
-  # string replaces it; "" clears it (see Insika::SecretMasking, the same pattern
-  # as the LLM api_keys).
+  # Credentials (`env`/`headers`) NEVER leave here in plaintext to the UI: the
+  # display reads (`get`/`all`) mask EACH value with the `__OCULTO__` sentinel.
+  # Only `get_raw`/`all_raw` (consumed by Insika::McpClient, never by the
+  # screen) return the real values. On write, the sentinel coming back
+  # preserves the value; a new string replaces it; "" clears it (see
+  # Insika::SecretMasking, the same pattern as the LLM api_keys).
   #
-  # Current scope: durable config CRUD (the instances UI). Running an MCP client
-  # against these instances is later runtime work — the store is the editable
-  # source from now on.
+  # Also holds `tools_cache` — the last live discovery result
+  # (Insika::McpToolRegistry#refresh writes it; `entries`/Studio/doctor read
+  # it for cheap display; tool EXECUTION never depends on it.
+  # Not a credential -> never masked.
+  #
+  # Durable config CRUD (the instances UI) + the shape
+  # Insika::McpClient.for/Insika::McpToolRegistry read.
   class McpStore
     include Coercion
 
@@ -48,10 +56,25 @@ module Insika
       names.filter_map { |n| raw(n) }
     end
 
-    # Upsert with per-env-key secret reconciliation. `attrs`
+    # System-written cache of the instance's discovered tools:
+    # Insika::McpToolRegistry#refresh connects live and writes the result here
+    # for cheap display (Studio/doctor/`entries`) — execution never reads it
+    # back, only the live client. NOT a credential -> never masked. -> the
+    # MASKED record (mirrors upsert's return).
+    def set_tools_cache(name, tools)
+      existing = raw(name)
+      raise Insika::NotFoundError, "MCP instance '#{name}' not found" if existing.nil?
+
+      record = existing.merge("tools_cache" => normalize_tools_cache(tools))
+      @cs.put(SCOPE, name, record)
+      mask(record)
+    end
+
+    # Upsert with per-key secret reconciliation. `attrs`
     # (string|symbol keys):
-    #   name (required), transport, command, url, description,
-    #   enabled (bool), env ({ "KEY" => value|sentinel|"" })
+    #   name (required), transport, command, args ([String, ...]), url,
+    #   description, enabled (bool), env ({ "KEY" => value|sentinel|"" }),
+    #   headers ({ "Header-Name" => value|sentinel|"" })
     # -> MASKED Hash (the stored record).
     def upsert(attrs)
       h = symbolize(attrs)
@@ -63,10 +86,15 @@ module Insika
         "name" => name,
         "transport" => presence(h[:transport]) || "stdio",
         "command" => presence(h[:command]),
+        "args" => Array(h[:args]).map(&:to_s).reject(&:empty?),
         "url" => presence(h[:url]),
         "description" => presence(h[:description]),
         "enabled" => h.fetch(:enabled, true) ? true : false,
-        "env" => reconcile_env(h[:env], existing && existing["env"])
+        "env" => reconcile_hash(h[:env], existing && existing["env"]),
+        "headers" => reconcile_hash(h[:headers], existing && existing["headers"]),
+        # editing an instance's connection details doesn't change its discovered
+        # tools -> preserved across upsert; only set_tools_cache writes it.
+        "tools_cache" => (existing && existing["tools_cache"]) || []
       }
       @cs.put(SCOPE, name, record)
       mask(record)
@@ -75,25 +103,69 @@ module Insika
     # -> bool (did it exist?).
     def delete(name) = @cs.delete(SCOPE, name.to_s)
 
+    # -> [String] names of http/sse instances still stored under the pre-
+    # Meaning of `env` (`insika doctor`'s "mcp" check; `raw`/`all_raw`
+    # already read them correctly — this is only to flag the ones that still
+    # need a re-save so the stored record itself catches up).
+    def legacy_header_names
+      names.select { |n| needs_header_migration?(@cs.get(SCOPE, n)) }
+    end
+
     private
 
-    def raw(name) = @cs.get(SCOPE, name.to_s)
+    def raw(name) = migrate_legacy_headers(@cs.get(SCOPE, name.to_s))
+
+    # A record written before used `env` as HTTP headers for an
+    # http/sse instance. On READ ONLY (never rewritten silently — `insika
+    # doctor` flags it via `legacy_header_names` so the operator re-saves it
+    # explicitly), an http/sse record with `env` set and no `headers` yet is
+    # read as if `env` had been `headers` all along. A stdio record's `env` is
+    # untouched — it always meant process environment.
+    def migrate_legacy_headers(record)
+      return record unless needs_header_migration?(record)
+
+      record.merge("headers" => record["env"], "env" => {})
+    end
 
-    # Each env value becomes the sentinel (or disappears if empty) — never leaks plaintext.
+    def needs_header_migration?(record)
+      return false if record.nil? || !http_like?(record["transport"])
+
+      (record["env"] || {}).any? && (record["headers"] || {}).empty?
+    end
+
+    def http_like?(transport) = %w[http sse].include?(transport.to_s)
+
+    # -> [{"name","description","inputSchema"}] string-keyed, dropping any
+    # entry without a name (nothing to register a Registry::Entry under).
+    def normalize_tools_cache(tools)
+      Array(tools).filter_map do |t|
+        h = stringify_hash(t)
+        name = presence(h["name"])
+        next nil if name.nil?
+
+        { "name" => name, "description" => h["description"].to_s, "inputSchema" => h["inputSchema"] || {} }
+      end
+    end
+
+    # Each env/headers value becomes the sentinel (or disappears if empty) — never leaks plaintext.
     def mask(record)
       return nil if record.nil?
 
-      env = (record["env"] || {}).each_with_object({}) do |(k, v), acc|
-        acc[k] = SecretMasking.mask(v)
-      end
-      record.merge("env" => env)
+      record.merge(
+        "env" => mask_hash(record["env"]),
+        "headers" => mask_hash(record["headers"])
+      )
+    end
+
+    def mask_hash(hash)
+      (hash || {}).each_with_object({}) { |(k, v), acc| acc[k] = SecretMasking.mask(v) }
     end
 
-    # Reconciles the env received from the form against the stored one, key by key: a
-    # key that came as the sentinel is preserved; a new string replaces it; "" (or missing
-    # from the submission) clears it. NEW keys are added; old keys absent from the form
-    # are removed (the form sends the complete set of keys).
-    def reconcile_env(incoming, existing)
+    # Reconciles a credential Hash received from the form against the stored one, key by
+    # key: a key that came as the sentinel is preserved; a new string replaces it; "" (or
+    # missing from the submission) clears it. NEW keys are added; old keys absent from the
+    # form are removed (the form sends the complete set of keys).
+    def reconcile_hash(incoming, existing)
       inc = stringify_hash(incoming)
       old = existing || {}
       inc.each_with_object({}) do |(k, v), acc|

data/lib/insika/mcp_tool_ingestor.rb

@@ -31,12 +31,19 @@ module Insika
   #     stdio has no HTTP endpoint -> raises a clear error (later work).
   #   - MCP session lifecycle (initialize/negotiation/session-id/notifications) and the
   #     UNWRAP of the `tools/call` response (`{content:[{type,text}]}`) — the binding
-  #     makes a stateless POST and returns the raw body (extract body_raw).
-  #   - Credential injection (the instance `env`) as an auth header in the HTTP
-  #     binding: the `env` is consumed by a real MCP client (deferred), not mapped
-  #     to a header here.
+  #     makes a stateless POST and returns the raw body (extract body_raw). A server
+  #     that requires the handshake before answering `tools/list`/`tools/call` is not
+  #     reachable yet — that IS the real transport, not this minimal client.
   #   - Tools whose name/top-level property is outside the ToolDefinition NAME_RE
   #     (uppercase/hyphens) are ISOLATED into `errors[]` by the import (R4).
+  #
+  # CREDENTIAL INJECTION: the instance `env` (Hash) is sent verbatim as HTTP
+  # headers, on BOTH the discovery request (`tools/list`, this file) and every
+  # ingested tool's `tools/call` binding (`build_manifest`'s `defaults.headers`)
+  # — literal header-name -> value, the same convention as a data-tool's own
+  # `secret_headers` (the operator types the full value, "Bearer xxx" included;
+  # no magic prefixing). An instance with no `env` sends the bare
+  # `Content-Type` header only, byte-for-byte what shipped before this.
   class McpToolIngestor
     def initialize(mcp_store:, import_tools:, client_factory: nil)
       @mcp_store = mcp_store
@@ -69,17 +76,32 @@ module Insika
       end
 
       tools = Array((client || @client_factory.call(record)).list_tools)
-      build_manifest(name.to_s, url, tools)
+      build_manifest(name.to_s, url, tools, env_headers(record))
     end
 
     private
 
-    def build_manifest(name, url, tools)
+    # `headers` (an http/sse instance's credentials — `env` reads
+    # as `headers` for these transports via McpStore's migration-on-read, see
+    # McpStore#migrate_legacy_headers) -> literal HTTP headers (header-NAME ->
+    # value; the value carries its own scheme, e.g. "Bearer xxx" — no magic
+    # prefixing). NOT `secret_headers`: ToolManifest's own rule for a secret
+    # header requires a `{{secret.*}}` reference, which is the opposite of what
+    # a literal credential is — so an MCP instance's headers are NOT masked in
+    # a tool's edit page in /studio/tools, unlike a hand-authored data-tool's
+    # Authorization header. Acceptable for now (Studio is already
+    # operator-gated); a real fix routes this through the deployment's own
+    # {{secret.*}}/{{env.*}} resolution instead — later work.
+    def env_headers(record)
+      (record["headers"] || {}).each_with_object({}) { |(k, v), acc| acc[k.to_s] = v.to_s }
+    end
+
+    def build_manifest(name, url, tools, headers)
       {
         "version" => 1,
         "defaults" => {
           "method" => "POST",
-          "headers" => { "Content-Type" => "application/json" },
+          "headers" => { "Content-Type" => "application/json" }.merge(headers),
           "response" => { "extract" => "body_raw" },
           "group" => "mcp:#{name}"
         },
@@ -127,7 +149,7 @@ module Insika
     end
 
     def default_client(record)
-      Insika::McpHttpClient.new(url: record["url"])
+      Insika::McpHttpClient.new(url: record["url"], headers: env_headers(record))
     end
 
     def presence(str) = Insika::Coercion.presence(str)