Merge pull request #10 from tgonzalezc5/feat/exa-search-mcp

feat: add Exa AI-powered search tool

Author: TKassis

README.md

@@ -23,7 +23,7 @@ It is built for scientists, analysts, and curious people who want a powerful AI
 - **Organise your work in projects.** Each project has its own files, chat history, and settings. Upload files, browse folders, preview documents, and download results - all from inside the app.
 - **Rich file previews.** Built-in viewers for code, Markdown (with math and diagrams), CSVs, PDFs, images, Jupyter notebooks, and bioinformatics formats (FASTA, FASTQ, VCF, BED, GFF, SAM, BCF).
 - **LaTeX editor.** Split-pane editor with live PDF compilation (pdfLaTeX, XeLaTeX, LuaLaTeX).
-- **Web search and document conversion.** Kady can search the web (via [Parallel](https://parallel.ai/)) and convert documents between formats (PDF, DOCX, HTML, etc.) with no extra setup.
+- **Web search and document conversion.** Kady can search the web (via [Exa](https://exa.ai/) or [Parallel](https://parallel.ai/)) and convert documents between formats (PDF, DOCX, HTML, etc.) with no extra setup.
 - **Voice input, drag-and-drop attachments, `@` file mentions,** and a **message queue** for batching up to 5 messages while the agent is working.
 - **Publication-ready provenance.** A timeline of every step in your session, plus a one-click "Copy as Methods" button that exports a paragraph ready to paste into a paper.
 - **Optional remote compute.** Plug in [Modal](https://modal.com/) to run heavy jobs on cloud GPUs (T4, L4, A10G, A100, H100) or serverless CPUs - selected right from the input bar.
@@ -35,7 +35,8 @@ It is built for scientists, analysts, and curious people who want a powerful AI
 |------|-----|-----------------|
 | A computer running **macOS or Linux** | The app runs locally on your machine | Windows works too - use [WSL](https://learn.microsoft.com/en-us/windows/wsl/install) |
 | An **OpenRouter API key** | This is how the AI models are accessed | [openrouter.ai](https://openrouter.ai/) - sign up and create a key |
-| A **Parallel API key** *(optional)* | Lets Kady search the web | [parallel.ai](https://parallel.ai/) |
+| An **Exa API key** *(optional)* | Lets Kady search the web with neural (embedding-based) retrieval tuned for scientific content | Get your Exa API key: [dashboard.exa.ai/api-keys](https://dashboard.exa.ai/api-keys) |
+| A **Parallel API key** *(optional)* | Alternative web search provider | [parallel.ai](https://parallel.ai/) |
 | **Modal** credentials *(optional)* | Only needed for remote GPU/CPU compute | [modal.com](https://modal.com/) |
 
 You do not need any coding experience. The startup script installs everything else for you.
@@ -55,7 +56,7 @@ cd k-dense-byok
 
 Inside the `kady_agent` folder you'll find a file called `env.example`. Make a copy and rename the copy to `.env` (note the dot at the start). Open `.env` in any text editor and paste your **OpenRouter API key** on the first line - that's the only key you need to get started.
 
-The file also has sections for other optional keys (Parallel for web search, Modal for remote compute, and many scientific and government database keys). Leave blank anything you don't need.
+The file also has sections for other optional keys (Exa or Parallel for web search, Modal for remote compute, and many scientific and government database keys). Leave blank anything you don't need.
 
 ### Step 3 - Start the app
 

docs/custom-mcp-servers.md

@@ -1,6 +1,6 @@
 # Custom MCP Servers
 
-K-Dense BYOK comes with built-in [MCP](https://modelcontextprotocol.io/) servers (Docling for document conversion and Parallel for web search). You can add your own MCP servers to give Kady's expert agents more tools - for example, connecting to internal databases, custom APIs, or specialised scientific tooling.
+K-Dense BYOK comes with built-in [MCP](https://modelcontextprotocol.io/) servers: Docling for document conversion, and two optional web-search providers — Exa and Parallel — each enabled by supplying the corresponding API key in `.env` (get an Exa key at [dashboard.exa.ai/api-keys](https://dashboard.exa.ai/api-keys)). You can add your own MCP servers to give Kady's expert agents more tools - for example, connecting to internal databases, custom APIs, or specialised scientific tooling.
 
 ## Adding a server through the UI
 
@@ -30,6 +30,6 @@ Two transport types are supported:
 
 ## How it's stored
 
-- Your custom servers are **merged** with the built-in defaults (Docling and Parallel) and passed to the Gemini CLI.
+- Your custom servers are **merged** with the built-in defaults (Docling, plus Exa and/or Parallel when their API keys are set) and passed to the Gemini CLI.
 - The configuration is saved **per project** in `projects/<project-id>/custom_mcps.json` (outside the `sandbox/` folder) so it survives sandbox deletion and app restarts.
 - Switching projects automatically swaps the MCP set - each project has its own.

kady_agent/agent.py

@@ -36,6 +36,7 @@
     or "openrouter/google/gemini-3.1-pro-preview"
 )
 EXTRA_HEADERS = {"X-Title": "Kady", "HTTP-Referer": "https://www.k-dense.ai"}
+EXA_API_KEY = os.getenv("EXA_API_KEY")
 PARALLEL_API_KEY = os.getenv("PARALLEL_API_KEY")
 
 logger = logging.getLogger(__name__)

kady_agent/env.example

@@ -30,6 +30,9 @@ OLLAMA_BASE_URL=http://localhost:11434
 
 ## Highly Recommended (Delete if not needed and filled in correctly)
 
+# Exa Search (get your key at https://dashboard.exa.ai/api-keys)
+EXA_API_KEY=
+
 # Parallel Search
 PARALLEL_API_KEY=
 

kady_agent/instructions/main_agent.md

@@ -20,7 +20,7 @@ Choose the lightest reliable path:
 You do **NOT** have the ability to activate or execute skills. Skills are capabilities that only the expert (Gemini CLI) inside `delegate_task` can use via its `activate_skill` tool. The skill reference table at the end of these instructions exists **solely** so you can:
 
 1. **Recognize** when a user names a skill (e.g. "use the parallel-web skill", "use literature-review").
-2. **Match** a user request to the most relevant skill(s) even when the user does not name one explicitly (e.g. a request for "research best places in SF" should suggest the `parallel-web` skill; a request to "write a report" should suggest the `writing` skill).
+2. **Match** a user request to the most relevant skill(s) even when the user does not name one explicitly (e.g. a request for "research best places in SF" should suggest the `exa-search` or `parallel-web` skill; a request to "write a report" should suggest the `writing` skill).
 3. **Pass the skill name(s) verbatim** in the `delegate_task` prompt so the expert can activate them.
 
 **Never** attempt to use, activate, or simulate a skill yourself. If a task needs a skill, delegate it.
@@ -31,15 +31,15 @@ You do **NOT** have the ability to activate or execute skills. Skills are capabi
 - In `prompt`, pass the user's request, the expert's role/objective/constraints, relevant context, file paths, URLs, and explicit success criteria.
 - Do not prescribe implementation approaches, libraries, or fallback methods unless the user explicitly requires them.
 - **Skills passthrough (MANDATORY):** If the user's message names specific skills (e.g. "use the parallel-web skill" or "use the skills: 'writing', 'literature-review'"), you MUST include an explicit instruction in the delegate prompt telling the expert to activate those skills. Use the format: `"You MUST activate and follow these skills: 'skill-name-1', 'skill-name-2'."` Do not paraphrase, omit, reorder, or summarize the skill list. The expert relies on exact names to activate the correct skills.
-- **Proactive skill matching:** Even when the user does not name a skill, consult the skill reference table and identify skills that match the task. Include them in the delegate prompt the same way: `"You should activate and follow these skills: 'skill-name'."` For example, if the user asks to "search the web for X", include the `parallel-web` skill; if they ask for a "literature review", include `literature-review` and `writing`.
+- **Proactive skill matching:** Even when the user does not name a skill, consult the skill reference table and identify skills that match the task. Include them in the delegate prompt the same way: `"You should activate and follow these skills: 'skill-name'."` For example, if the user asks to "search the web for X", include whichever web-search skill matches the enabled MCP (`exa-search` for Exa Search MCP, `parallel-web` for Parallel Search MCP); if they ask for a "literature review", include `literature-review` and `writing`.
 - **Modal compute passthrough (MANDATORY):** If the user's prompt requests specific compute infrastructure and mentions **Modal** (e.g. "run this on Modal", "use Modal GPUs", "deploy on Modal"), you MUST:
   1. Include the compute requirement explicitly in the `delegate_task` prompt.
   2. State that the expert **MUST activate and follow the `modal` skill** before writing or running any Modal-related code.
   3. Do not assume the expert will infer Modal usage on its own — spell it out: "You must activate and follow the skill: 'modal' to execute this code on a Modal instance."
 
 ## Tool preferences
 
-- Prefer Parallel Search MCP (`web_search`, `web_fetch`) for open-web search and URL content retrieval.
+- Prefer Exa Search MCP or Parallel Search MCP for open-web search and URL content retrieval — whichever is available. Both expose MCP tools for search and content fetch; the user's `.env` determines which one (or both) are enabled.
 - Prefer Docling for document conversion, text extraction, and markdown export.
 - Users may install custom MCP tools (e.g. memory/knowledge-graph, filesystem, databases, specialized APIs) via the Settings panel. These tools appear alongside the built-in ones — use them directly whenever the request matches their capabilities instead of routing through `delegate_task`.
 - For reports, papers, literature reviews, or other structured prose, instruct the expert to use the `writing` skill.

kady_agent/manifest.py

@@ -188,6 +188,19 @@ def _mcp_servers_snapshot() -> list[dict]:
     entries: list[dict] = []
     for name in sorted(merged):
         entries.append({"name": name, "spec": merged[name]})
+    if os.getenv("EXA_API_KEY"):
+        entries.append(
+            {
+                "name": "exa-search",
+                "spec": {
+                    "httpUrl": "https://mcp.exa.ai/mcp",
+                    "headers": {
+                        "x-api-key": "YOUR_EXA_API_KEY",
+                        "x-exa-integration": "k-dense-byok",
+                    },
+                },
+            }
+        )
     if os.getenv("PARALLEL_API_KEY"):
         entries.append(
             {

kady_agent/mcps.py

@@ -168,6 +168,22 @@ async def close(self) -> None:
 
 all_mcps: list[BaseToolset] = []
 
+if os.getenv("EXA_API_KEY"):
+    exa_search_mcp = ResilientMcpToolset(
+        McpToolset(
+            connection_params=StreamableHTTPConnectionParams(
+                url="https://mcp.exa.ai/mcp",
+                headers={
+                    "x-api-key": os.getenv("EXA_API_KEY"),
+                    "x-exa-integration": "k-dense-byok",
+                },
+                timeout=600,
+            ),
+        ),
+        label="Exa Search MCP",
+    )
+    all_mcps.append(exa_search_mcp)
+
 if os.getenv("PARALLEL_API_KEY"):
     parallel_search_mcp = ResilientMcpToolset(
         McpToolset(

tests/test_manifest.py

@@ -178,3 +178,52 @@ def mutator(m: dict) -> None:
     # Persisted
     reread = manifest_module.read_manifest("s4", turn_id)
     assert reread["citations"]["total"] == 3
+
+
+# ---------------------------------------------------------------------------
+# _mcp_servers_snapshot — built-in MCP registration
+# ---------------------------------------------------------------------------
+
+
+def test_mcp_snapshot_includes_parallel_when_key_set(active_project, monkeypatch):
+    monkeypatch.setenv("PARALLEL_API_KEY", "test-parallel")
+    monkeypatch.delenv("EXA_API_KEY", raising=False)
+    entries = manifest_module._mcp_servers_snapshot()
+    names = [entry["name"] for entry in entries]
+    assert "parallel-search" in names
+    assert "exa-search" not in names
+    parallel = next(e for e in entries if e["name"] == "parallel-search")
+    # Keys are redacted before they hit disk.
+    assert parallel["spec"]["headers"]["Authorization"] == "Bearer <redacted>"
+
+
+def test_mcp_snapshot_includes_exa_when_key_set(active_project, monkeypatch):
+    monkeypatch.setenv("EXA_API_KEY", "test-exa")
+    monkeypatch.delenv("PARALLEL_API_KEY", raising=False)
+    entries = manifest_module._mcp_servers_snapshot()
+    names = [entry["name"] for entry in entries]
+    assert "exa-search" in names
+    assert "parallel-search" not in names
+    exa = next(e for e in entries if e["name"] == "exa-search")
+    assert exa["spec"]["httpUrl"] == "https://mcp.exa.ai/mcp"
+    # API key redacted to a clear placeholder; integration header preserved verbatim.
+    assert exa["spec"]["headers"]["x-api-key"] == "YOUR_EXA_API_KEY"
+    assert exa["spec"]["headers"]["x-exa-integration"] == "k-dense-byok"
+
+
+def test_mcp_snapshot_omits_both_when_keys_unset(active_project, monkeypatch):
+    monkeypatch.delenv("PARALLEL_API_KEY", raising=False)
+    monkeypatch.delenv("EXA_API_KEY", raising=False)
+    entries = manifest_module._mcp_servers_snapshot()
+    names = [entry["name"] for entry in entries]
+    assert "parallel-search" not in names
+    assert "exa-search" not in names
+
+
+def test_mcp_snapshot_includes_both_when_both_keys_set(active_project, monkeypatch):
+    monkeypatch.setenv("PARALLEL_API_KEY", "test-parallel")
+    monkeypatch.setenv("EXA_API_KEY", "test-exa")
+    entries = manifest_module._mcp_servers_snapshot()
+    names = [entry["name"] for entry in entries]
+    assert "parallel-search" in names
+    assert "exa-search" in names