⚠️ Why not Brave Search?

The original plan used Brave Search — but its API requires a credit card to activate, which isn't workable for a class. We use the DuckDuckGo MCP server instead:

• Keyless — no account, no API key, no credit card
• Same stdio transport, same registration pattern
• Exposes two tools: search and fetch_content

⚠️ One trade-off: DuckDuckGo's free endpoint can rate-limit a busy shared network (a whole classroom on one venue IP). We plan for that below with an offline mock-search fallback — so the lab never hard-stops.

Prerequisites

• Antigravity installed, signed in, MCP config reachable (from Lab 0)
• Node.js v20+ (node -v)
• For DuckDuckGo search: uv / uvx available (Python tool runner)
  • Check: uvx --version. If missing, install uv (see facilitator note) — or skip straight to the mock-search fallback, which needs only Node.

✅ Checkpoint 0: node -v works, and either uvx --version works or you'll use the mock server.

Part 1 · The Filesystem server (10 min)

A pre-built server that lets the agent read/write files in a folder you choose.

Step 1 — Open Antigravity's MCP config

Agent panel → "…" (Additional Options) → MCP Servers → Manage MCP Servers → View raw config

⚠️ Check current UI: labels vary by build; this opens mcp_config.json (under ~/.gemini/antigravity/).

Step 2 — Add the filesystem server

Add to the mcpServers object. Point it at your workshop folder:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "ABSOLUTE_PATH_TO/stacklog-workshop"
      ]
    }
  }
}

Get the absolute path:

🪟  in the folder: cd        (prints it; double every \ → \\ in JSON)
🍎🐧 in the folder: pwd

Step 3 — Reload and verify

Save → Settings → Customizations → Installed MCP Servers → Refresh (or restart Antigravity).

✅ Checkpoint 1: the filesystem server appears in the MCP panel with its tools (read_file, write_file, list_directory, …).

Ask the agent:

List the files in my workshop folder.

✅ It calls the filesystem tool and returns your files — the agent just used a tool you didn't write.

Part 2 · The Search server (15 min)

Step 4 — Add the DuckDuckGo search server (primary)

Add a second entry alongside filesystem:

{
  "mcpServers": {
    "filesystem": { "...": "from Part 1" },

    "ddg-search": {
      "command": "uvx",
      "args": ["--with", "duckduckgo-mcp-server[browser]",
               "duckduckgo-mcp-server", "--fetch-backend", "auto"]
    }
  }
}

💡 Why --fetch-backend auto: it tries a fast plain fetch first and falls back to a browser-style fetch on a 403 / challenge — useful when a shared venue IP starts getting blocked. The simplest form "args": ["duckduckgo-mcp-server"] also works if uv extras are a problem.

Save → Refresh / restart.

✅ Checkpoint 2: ddg-search appears with tools search and fetch_content.

Step 5 — Test the search

Ask the agent:

Search the web for "what is the Model Context Protocol" and
summarise the top result in two sentences.

✅ The agent calls search, reads results, and answers.

⚠️ If search fails or stalls (rate-limited / network): don't fight it — switch to the mock-search fallback in Step 6. The lab continues either way.

Step 6 — The offline fallback (mock-search)

If DuckDuckGo is rate-limited (likely if the whole room searches at once), use the mock-search server — fully offline, keyless, Node-only, same tool shape.

From the mock-search-mcp starter folder:

npm install

Add it to mcp_config.json (you can keep it permanently as a backup):

{
  "mcpServers": {
    "mock-search": {
      "command": "npx",
      "args": ["tsx", "ABSOLUTE_PATH/mock-search-mcp/src/index.ts"]
    }
  }
}

Save → Refresh. It exposes the same search / fetch_content tools.

✅ Fallback checkpoint: ask the same search question; the agent now gets deterministic offline results and the pipeline flows. The agent can't tell the difference — you're learning tool-chaining, not DuckDuckGo.

Step 7 — Watch it in MCP Inspector (optional but recommended)

In a terminal:

npx @modelcontextprotocol/inspector

Connect to either search server via stdio and fire the search tool by hand. Watch the raw JSON-RPC request and response — this is the protocol from the MCP session, made visible.

✅ Checkpoint 3: you've seen a tool call as raw protocol, not just a chat answer.

Lab 1 success criteria

• [ ] filesystem server connected; agent listed your files
• [ ] A search server connected (ddg-search or mock-search) with search + fetch_content
• [ ] Agent answered a question using the search tool
• [ ] (Optional) Saw a raw tool call in MCP Inspector

All four can pass entirely offline via mock-search. Live DuckDuckGo is the bonus.

Bridge to Lab 2

You've now used other people's MCP servers. You've seen the Host → Server → Tool path fire live.
In Lab 2 you stop using and start building: your own MCP server, with tools an AI will call — the StackLog data layer.