mcpd: Go MCP SDK port — replaces Bun mcp-server tool surface

New cmd/mcpd binary using github.com/modelcontextprotocol/go-sdk
v1.5.0 over stdio transport. Exposes Lakehouse capabilities as MCP
tools: list_datasets, get_manifest, query_sql, embed_text,
search_vectors. Each tool proxies to the gateway via HTTP.

Replaces the MCP-tool subset of the Rust system's Bun mcp-server.ts
(the audit's "split this 2520-line empire" finding from R-005). HTTP
demo routes (the staffing co-pilot UI at /api/intelligence/*,
/headshots/*, etc.) stay Bun until G5 cutover — those are demo-
specific and depend on matrix-indexer signals not yet ported.

Architecture:
  cmd/mcpd/main.go (235 LoC)
    main() reads --gateway flag, builds server via buildServer(),
    runs on StdioTransport. Each tool's args is a typed struct with
    jsonschema tags (the SDK's canonical pattern); reflection
    generates the JSON Schema automatically.

    gatewayClient: thin HTTP wrapper over the configured gateway URL.
    30s per-request timeout. 16 MiB tool-response cap. Non-2xx
    surfaces as IsError CallToolResult (NOT as transport error) so
    the LLM caller sees the error text and can decide how to react.

    proxy() handles GET + POST + JSON body uniformly. errorResult()
    + jsonResult() helpers normalize CallToolResult shape.

  cmd/mcpd/main_test.go (13 test funcs)
    Tests the full MCP wire end-to-end without a subprocess: spin
    up a fake gateway via httptest, build the MCP server pointed at
    it, connect a client via in-memory transports (NewInMemoryTransports),
    call each tool. Each tool gets:
      - happy path (gateway returns 200 → tool returns content)
      - input validation (missing required fields → IsError)
      - upstream error (gateway 4xx → tool returns IsError)
    Plus TestListTools verifies all 5 tools register; TestGatewayUnreachable
    verifies network-level failures surface as IsError, not panics.

Setup for Claude Desktop / Code documented in README:
  {
    "mcpServers": {
      "lakehouse": {
        "command": "/path/to/bin/mcpd",
        "args": ["--gateway", "http://127.0.0.1:3110"]
      }
    }
  }

Verified:
  go test -count=1 ./cmd/mcpd/  — 13/13 green
  just verify                    — vet + test + 9 smokes 35s

Out of scope for this commit:
  - Resources (mcp.AddResource): not needed yet; tools cover the
    interactive surface. Add when an LLM-side use case shows up.
  - Prompts (mcp.AddPrompt): same.
  - Streamable transports (HTTP, SSE): stdio is the universal one;
    streamable can be added with srv.Run(ctx, &mcp.StreamableHTTPHandler{})
    swap if a daemon-mode deploy makes sense.
  - mcpd inside the daemon-supervised stack: it's stdio-only and
    spawned by the MCP client, not run as a service. Adding a
    daemon-mode (HTTP transport on a port) is a follow-up if MCP
    consumers want long-lived sessions.

This is a tool-surface only port. The Bun mcp-server.ts also serves
HTTP demo routes (/api/catalog/datasets, /intelligence/*, /headshots/*)
that depend on the matrix-indexer signals from the Rust system; those
stay Bun until G5 cutover when the staffing co-pilot service ports
to Go.

Direct deps added:
  github.com/modelcontextprotocol/go-sdk v1.5.0

Transitive (resolved by go mod tidy):
  github.com/google/jsonschema-go        v0.4.2
  github.com/yosida95/uritemplate/v3     v3.0.2
  golang.org/x/oauth2                    v0.35.0
  github.com/segmentio/encoding          v0.5.4
  github.com/golang-jwt/jwt/v5           v5.3.1

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

README.md

@@ -38,6 +38,28 @@ real-scale validation + G1/G1P/G2 pointer at the bottom).
 | `queryd` | 3214 | DuckDB SELECT over registered Parquets via httpfs |
 | `vectord` | 3215 | HNSW vector search (+ optional persistence to storaged) |
 | `embedd` | 3216 | Text → vector via Ollama (default `nomic-embed-text` 768-d) |
+| `mcpd`    | stdio | Model Context Protocol server (Claude Desktop / Code consumers) |
+
+## MCP server
+
+`bin/mcpd` exposes Lakehouse capabilities as MCP tools over stdio:
+`list_datasets`, `get_manifest`, `query_sql`, `embed_text`, `search_vectors`.
+All tools proxy to the gateway, so the gateway must be up first.
+
+Wire into Claude Desktop / Claude Code by adding to the MCP config:
+```json
+{
+  "mcpServers": {
+    "lakehouse": {
+      "command": "/path/to/golangLAKEHOUSE/bin/mcpd",
+      "args": ["--gateway", "http://127.0.0.1:3110"]
+    }
+  }
+}
+```
+
+Replaces the Bun `mcp-server.ts` MCP-tool surface from the Rust system.
+HTTP demo routes (the staffing co-pilot UI) stay Bun until G5.
 
 ## Acceptance smokes
 

cmd/mcpd/main.go

@@ -0,0 +1,268 @@
+// mcpd is the Model Context Protocol server that exposes Lakehouse
+// capabilities as MCP tools. Replaces the Bun mcp-server.ts surface
+// (the MCP-tool-only subset; HTTP demo routes stay Bun until G5).
+//
+// Tools exposed:
+//   list_datasets     GET  /v1/catalog/list
+//   get_manifest      GET  /v1/catalog/manifest/<name>
+//   query_sql         POST /v1/sql
+//   embed_text        POST /v1/embed
+//   search_vectors    POST /v1/vectors/index/<name>/search
+//
+// Transport: StdioTransport (the universal MCP transport — Claude
+// Desktop, Claude Code, MCP CLI all speak this). Other transports
+// (SSE, HTTP) can be added later by changing the Run call.
+//
+// Setup for Claude Desktop / Claude Code:
+//   bin/mcpd --gateway http://127.0.0.1:3110
+//   (configure your client to spawn this binary as an MCP server)
+//
+// Why not in cmd/gateway: separation of concerns. Gateway is HTTP
+// for direct-API callers; mcpd is stdio for MCP consumers. Keeping
+// them separate means each can be deployed / restarted / monitored
+// without affecting the other.
+package main
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"flag"
+	"fmt"
+	"io"
+	"log"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+func main() {
+	gatewayURL := flag.String("gateway", "http://127.0.0.1:3110",
+		"Gateway URL (where mcpd proxies all tool calls)")
+	flag.Parse()
+
+	srv := buildServer(*gatewayURL)
+
+	if err := srv.Run(context.Background(), &mcp.StdioTransport{}); err != nil {
+		log.Fatalf("mcpd: %v", err)
+	}
+}
+
+// buildServer assembles the MCP server with all tools wired against
+// the given gateway URL. Extracted from main() so tests can build
+// the server with a test gateway URL.
+func buildServer(gatewayURL string) *mcp.Server {
+	srv := mcp.NewServer(&mcp.Implementation{
+		Name:    "lakehouse",
+		Version: "v0.1.0",
+	}, nil)
+
+	gw := newGatewayClient(gatewayURL)
+
+	mcp.AddTool(srv, &mcp.Tool{
+		Name: "list_datasets",
+		Description: "List all datasets registered in the catalog. " +
+			"Returns dataset_id, name, schema_fingerprint, row_count " +
+			"per dataset.",
+	}, gw.listDatasets)
+
+	mcp.AddTool(srv, &mcp.Tool{
+		Name: "get_manifest",
+		Description: "Fetch the manifest for a single dataset by name. " +
+			"Includes schema fingerprint, parquet object keys, row count, " +
+			"created_at_unix_ns.",
+	}, gw.getManifest)
+
+	mcp.AddTool(srv, &mcp.Tool{
+		Name: "query_sql",
+		Description: "Execute a SQL query against the registered datasets. " +
+			"Returns columns + rows. SQL is interpreted by DuckDB; standard " +
+			"SQL plus DuckDB-specific functions (read_parquet, etc.) work.",
+	}, gw.querySQL)
+
+	mcp.AddTool(srv, &mcp.Tool{
+		Name: "embed_text",
+		Description: "Embed one or more texts via the configured embedding " +
+			"model (default: nomic-embed-text). Returns one vector per text " +
+			"in the same order as the input.",
+	}, gw.embedText)
+
+	mcp.AddTool(srv, &mcp.Tool{
+		Name: "search_vectors",
+		Description: "Find the top-K nearest neighbors of a query vector " +
+			"in the named HNSW index. K defaults to 10 if omitted.",
+	}, gw.searchVectors)
+
+	return srv
+}
+
+// gatewayClient holds the HTTP client + base URL for proxying tool
+// calls to the Go gateway. Per-tool latency is on the order of a
+// gateway round-trip; the 30s timeout accommodates the slowest
+// expected SQL query without holding stdio sessions indefinitely.
+type gatewayClient struct {
+	baseURL string
+	hc      *http.Client
+}
+
+func newGatewayClient(baseURL string) *gatewayClient {
+	return &gatewayClient{
+		baseURL: strings.TrimRight(baseURL, "/"),
+		hc:      &http.Client{Timeout: 30 * time.Second},
+	}
+}
+
+// ── tool argument structs (jsonschema tags drive schema generation) ──
+
+type listDatasetsArgs struct{}
+
+type getManifestArgs struct {
+	Name string `json:"name" jsonschema:"the dataset name to fetch"`
+}
+
+type querySQLArgs struct {
+	SQL string `json:"sql" jsonschema:"the SQL query to execute"`
+}
+
+type embedTextArgs struct {
+	Texts []string `json:"texts" jsonschema:"the texts to embed"`
+	Model string   `json:"model,omitempty" jsonschema:"optional model name (defaults to embedd's configured default)"`
+}
+
+type searchVectorsArgs struct {
+	IndexName string    `json:"index_name" jsonschema:"the index to search"`
+	Vector    []float32 `json:"vector" jsonschema:"the query vector"`
+	K         int       `json:"k,omitempty" jsonschema:"top-K to return (default 10)"`
+}
+
+// ── tool handlers ──
+
+func (g *gatewayClient) listDatasets(ctx context.Context, _ *mcp.CallToolRequest, _ listDatasetsArgs) (*mcp.CallToolResult, any, error) {
+	body, err := g.proxy(ctx, http.MethodGet, "/v1/catalog/list", nil)
+	if err != nil {
+		return errorResult(err), nil, nil
+	}
+	return jsonResult(body), nil, nil
+}
+
+func (g *gatewayClient) getManifest(ctx context.Context, _ *mcp.CallToolRequest, args getManifestArgs) (*mcp.CallToolResult, any, error) {
+	if args.Name == "" {
+		return errorResult(fmt.Errorf("name is required")), nil, nil
+	}
+	path := "/v1/catalog/manifest/" + url.PathEscape(args.Name)
+	body, err := g.proxy(ctx, http.MethodGet, path, nil)
+	if err != nil {
+		return errorResult(err), nil, nil
+	}
+	return jsonResult(body), nil, nil
+}
+
+func (g *gatewayClient) querySQL(ctx context.Context, _ *mcp.CallToolRequest, args querySQLArgs) (*mcp.CallToolResult, any, error) {
+	if strings.TrimSpace(args.SQL) == "" {
+		return errorResult(fmt.Errorf("sql is required")), nil, nil
+	}
+	reqBody, _ := json.Marshal(map[string]string{"sql": args.SQL})
+	body, err := g.proxy(ctx, http.MethodPost, "/v1/sql", reqBody)
+	if err != nil {
+		return errorResult(err), nil, nil
+	}
+	return jsonResult(body), nil, nil
+}
+
+func (g *gatewayClient) embedText(ctx context.Context, _ *mcp.CallToolRequest, args embedTextArgs) (*mcp.CallToolResult, any, error) {
+	if len(args.Texts) == 0 {
+		return errorResult(fmt.Errorf("texts is required")), nil, nil
+	}
+	payload := map[string]any{"texts": args.Texts}
+	if args.Model != "" {
+		payload["model"] = args.Model
+	}
+	reqBody, _ := json.Marshal(payload)
+	body, err := g.proxy(ctx, http.MethodPost, "/v1/embed", reqBody)
+	if err != nil {
+		return errorResult(err), nil, nil
+	}
+	return jsonResult(body), nil, nil
+}
+
+func (g *gatewayClient) searchVectors(ctx context.Context, _ *mcp.CallToolRequest, args searchVectorsArgs) (*mcp.CallToolResult, any, error) {
+	if args.IndexName == "" {
+		return errorResult(fmt.Errorf("index_name is required")), nil, nil
+	}
+	if len(args.Vector) == 0 {
+		return errorResult(fmt.Errorf("vector is required")), nil, nil
+	}
+	payload := map[string]any{"vector": args.Vector}
+	if args.K > 0 {
+		payload["k"] = args.K
+	}
+	reqBody, _ := json.Marshal(payload)
+	path := "/v1/vectors/index/" + url.PathEscape(args.IndexName) + "/search"
+	body, err := g.proxy(ctx, http.MethodPost, path, reqBody)
+	if err != nil {
+		return errorResult(err), nil, nil
+	}
+	return jsonResult(body), nil, nil
+}
+
+// proxy makes a request to the gateway and returns the response body
+// on success. Non-2xx status codes return an error with the body
+// preview in the message — surfaced to the MCP client as a tool error
+// rather than a transport-level failure.
+func (g *gatewayClient) proxy(ctx context.Context, method, path string, body []byte) ([]byte, error) {
+	var rdr io.Reader
+	if body != nil {
+		rdr = bytes.NewReader(body)
+	}
+	req, err := http.NewRequestWithContext(ctx, method, g.baseURL+path, rdr)
+	if err != nil {
+		return nil, fmt.Errorf("build request: %w", err)
+	}
+	if body != nil {
+		req.Header.Set("Content-Type", "application/json")
+	}
+	resp, err := g.hc.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("call gateway: %w", err)
+	}
+	defer resp.Body.Close()
+	respBody, _ := io.ReadAll(io.LimitReader(resp.Body, 16<<20)) // 16 MiB tool-response cap
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		preview := respBody
+		if len(preview) > 512 {
+			preview = preview[:512]
+		}
+		return nil, fmt.Errorf("gateway %s %s: status %d: %s",
+			method, path, resp.StatusCode, string(preview))
+	}
+	return respBody, nil
+}
+
+// errorResult wraps an error as an MCP tool error result. The MCP
+// protocol distinguishes "tool ran but reported failure" (returned
+// in CallToolResult.IsError + content) from "tool threw" (returned
+// as the third return value). We use the former so the LLM caller
+// sees the error text and can decide how to react, rather than
+// surfacing the error as transport noise.
+func errorResult(err error) *mcp.CallToolResult {
+	return &mcp.CallToolResult{
+		IsError: true,
+		Content: []mcp.Content{
+			&mcp.TextContent{Text: err.Error()},
+		},
+	}
+}
+
+// jsonResult wraps a JSON byte slice as a successful tool result.
+// The content is text — MCP clients render it; LLMs parse it as
+// JSON when their tool config indicates so.
+func jsonResult(body []byte) *mcp.CallToolResult {
+	return &mcp.CallToolResult{
+		Content: []mcp.Content{
+			&mcp.TextContent{Text: string(body)},
+		},
+	}
+}

cmd/mcpd/main_test.go

@@ -0,0 +1,282 @@
+package main
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+// Tests the MCP tool surface end-to-end without a subprocess: spin
+// up a fake gateway via httptest, build the MCP server pointed at
+// it, connect a client via in-memory transports, call each tool.
+
+// fakeGateway returns an httptest.Server that responds to the routes
+// mcpd proxies. Each route's handler is configurable via the routes map.
+func fakeGateway(t *testing.T, routes map[string]http.HandlerFunc) *httptest.Server {
+	t.Helper()
+	mux := http.NewServeMux()
+	for path, h := range routes {
+		mux.HandleFunc(path, h)
+	}
+	mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
+		t.Errorf("fakeGateway: unexpected route %s %s", r.Method, r.URL.Path)
+		http.NotFound(w, r)
+	})
+	srv := httptest.NewServer(mux)
+	t.Cleanup(srv.Close)
+	return srv
+}
+
+// connect builds the mcpd server pointed at gatewayURL, connects an
+// in-memory client, and returns a ready-to-use ClientSession.
+func connect(t *testing.T, gatewayURL string) *mcp.ClientSession {
+	t.Helper()
+	ctx := context.Background()
+
+	srv := buildServer(gatewayURL)
+	client := mcp.NewClient(&mcp.Implementation{Name: "test-client", Version: "v0.0.1"}, nil)
+
+	t1, t2 := mcp.NewInMemoryTransports()
+	if _, err := srv.Connect(ctx, t1, nil); err != nil {
+		t.Fatalf("server connect: %v", err)
+	}
+	session, err := client.Connect(ctx, t2, nil)
+	if err != nil {
+		t.Fatalf("client connect: %v", err)
+	}
+	t.Cleanup(func() { _ = session.Close() })
+	return session
+}
+
+func callTool(t *testing.T, session *mcp.ClientSession, name string, args any) *mcp.CallToolResult {
+	t.Helper()
+	res, err := session.CallTool(context.Background(), &mcp.CallToolParams{
+		Name:      name,
+		Arguments: args,
+	})
+	if err != nil {
+		t.Fatalf("CallTool %s: %v", name, err)
+	}
+	return res
+}
+
+func resultText(t *testing.T, res *mcp.CallToolResult) string {
+	t.Helper()
+	if len(res.Content) == 0 {
+		t.Fatal("result has no content")
+	}
+	tc, ok := res.Content[0].(*mcp.TextContent)
+	if !ok {
+		t.Fatalf("first content is %T, want *mcp.TextContent", res.Content[0])
+	}
+	return tc.Text
+}
+
+func TestListTools(t *testing.T) {
+	gw := fakeGateway(t, nil)
+	session := connect(t, gw.URL)
+
+	res, err := session.ListTools(context.Background(), nil)
+	if err != nil {
+		t.Fatalf("ListTools: %v", err)
+	}
+	want := map[string]bool{
+		"list_datasets":  false,
+		"get_manifest":   false,
+		"query_sql":      false,
+		"embed_text":     false,
+		"search_vectors": false,
+	}
+	for _, tool := range res.Tools {
+		if _, ok := want[tool.Name]; ok {
+			want[tool.Name] = true
+		}
+	}
+	for name, found := range want {
+		if !found {
+			t.Errorf("expected tool %q exposed by mcpd, not in ListTools", name)
+		}
+	}
+}
+
+func TestListDatasets_HappyPath(t *testing.T) {
+	gw := fakeGateway(t, map[string]http.HandlerFunc{
+		"/v1/catalog/list": func(w http.ResponseWriter, _ *http.Request) {
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = w.Write([]byte(`{"manifests":[{"name":"workers","row_count":500000}],"count":1}`))
+		},
+	})
+	session := connect(t, gw.URL)
+
+	res := callTool(t, session, "list_datasets", listDatasetsArgs{})
+	if res.IsError {
+		t.Fatalf("expected success, got IsError with: %s", resultText(t, res))
+	}
+	body := resultText(t, res)
+	if !strings.Contains(body, "workers") || !strings.Contains(body, "500000") {
+		t.Errorf("response missing expected fields: %s", body)
+	}
+}
+
+func TestGetManifest_HappyPath(t *testing.T) {
+	gw := fakeGateway(t, map[string]http.HandlerFunc{
+		"/v1/catalog/manifest/workers": func(w http.ResponseWriter, _ *http.Request) {
+			_, _ = w.Write([]byte(`{"name":"workers","row_count":500000,"schema_fingerprint":"sha256:abc"}`))
+		},
+	})
+	session := connect(t, gw.URL)
+
+	res := callTool(t, session, "get_manifest", getManifestArgs{Name: "workers"})
+	if res.IsError {
+		t.Fatalf("expected success, got: %s", resultText(t, res))
+	}
+	body := resultText(t, res)
+	if !strings.Contains(body, "workers") {
+		t.Errorf("missing manifest fields in response: %s", body)
+	}
+}
+
+func TestGetManifest_EmptyName_IsError(t *testing.T) {
+	gw := fakeGateway(t, nil) // no handlers — tool should error before hitting gateway
+	session := connect(t, gw.URL)
+
+	res := callTool(t, session, "get_manifest", getManifestArgs{Name: ""})
+	if !res.IsError {
+		t.Fatal("expected IsError on empty name")
+	}
+}
+
+func TestQuerySQL_HappyPath(t *testing.T) {
+	gw := fakeGateway(t, map[string]http.HandlerFunc{
+		"/v1/sql": func(w http.ResponseWriter, r *http.Request) {
+			if r.Method != "POST" {
+				t.Errorf("/v1/sql got %s, want POST", r.Method)
+			}
+			_, _ = w.Write([]byte(`{"columns":[{"name":"n","type":"BIGINT"}],"rows":[[5]],"row_count":1}`))
+		},
+	})
+	session := connect(t, gw.URL)
+
+	res := callTool(t, session, "query_sql", querySQLArgs{SQL: "SELECT count(*) FROM workers"})
+	if res.IsError {
+		t.Fatalf("expected success, got: %s", resultText(t, res))
+	}
+	if !strings.Contains(resultText(t, res), `"row_count":1`) {
+		t.Errorf("response missing row_count field: %s", resultText(t, res))
+	}
+}
+
+func TestQuerySQL_EmptySQL_IsError(t *testing.T) {
+	gw := fakeGateway(t, nil)
+	session := connect(t, gw.URL)
+
+	res := callTool(t, session, "query_sql", querySQLArgs{SQL: "   "})
+	if !res.IsError {
+		t.Fatal("expected IsError on whitespace SQL")
+	}
+}
+
+func TestEmbedText_HappyPath(t *testing.T) {
+	gw := fakeGateway(t, map[string]http.HandlerFunc{
+		"/v1/embed": func(w http.ResponseWriter, _ *http.Request) {
+			_, _ = w.Write([]byte(`{"model":"nomic-embed-text","dimension":768,"vectors":[[0.1,0.2]]}`))
+		},
+	})
+	session := connect(t, gw.URL)
+
+	res := callTool(t, session, "embed_text", embedTextArgs{Texts: []string{"hello"}})
+	if res.IsError {
+		t.Fatalf("expected success, got: %s", resultText(t, res))
+	}
+	if !strings.Contains(resultText(t, res), `"dimension":768`) {
+		t.Errorf("missing dimension in response: %s", resultText(t, res))
+	}
+}
+
+func TestEmbedText_EmptyTexts_IsError(t *testing.T) {
+	gw := fakeGateway(t, nil)
+	session := connect(t, gw.URL)
+
+	res := callTool(t, session, "embed_text", embedTextArgs{Texts: nil})
+	if !res.IsError {
+		t.Fatal("expected IsError on empty texts")
+	}
+}
+
+func TestSearchVectors_HappyPath(t *testing.T) {
+	gw := fakeGateway(t, map[string]http.HandlerFunc{
+		"/v1/vectors/index/test_idx/search": func(w http.ResponseWriter, _ *http.Request) {
+			_, _ = w.Write([]byte(`{"results":[{"id":"v1","distance":0.001}]}`))
+		},
+	})
+	session := connect(t, gw.URL)
+
+	res := callTool(t, session, "search_vectors", searchVectorsArgs{
+		IndexName: "test_idx",
+		Vector:    []float32{1, 0, 0, 0},
+		K:         5,
+	})
+	if res.IsError {
+		t.Fatalf("expected success, got: %s", resultText(t, res))
+	}
+	if !strings.Contains(resultText(t, res), `"id":"v1"`) {
+		t.Errorf("missing top-1 in response: %s", resultText(t, res))
+	}
+}
+
+func TestSearchVectors_MissingIndex_IsError(t *testing.T) {
+	gw := fakeGateway(t, nil)
+	session := connect(t, gw.URL)
+
+	res := callTool(t, session, "search_vectors", searchVectorsArgs{
+		Vector: []float32{1, 0, 0, 0},
+	})
+	if !res.IsError {
+		t.Fatal("expected IsError on missing index_name")
+	}
+}
+
+func TestSearchVectors_MissingVector_IsError(t *testing.T) {
+	gw := fakeGateway(t, nil)
+	session := connect(t, gw.URL)
+
+	res := callTool(t, session, "search_vectors", searchVectorsArgs{
+		IndexName: "test_idx",
+	})
+	if !res.IsError {
+		t.Fatal("expected IsError on missing vector")
+	}
+}
+
+func TestGatewayError_PropagatesAsIsError(t *testing.T) {
+	gw := fakeGateway(t, map[string]http.HandlerFunc{
+		"/v1/sql": func(w http.ResponseWriter, _ *http.Request) {
+			w.WriteHeader(http.StatusBadRequest)
+			_, _ = w.Write([]byte("syntax error: no such table"))
+		},
+	})
+	session := connect(t, gw.URL)
+
+	res := callTool(t, session, "query_sql", querySQLArgs{SQL: "SELECT * FROM nope"})
+	if !res.IsError {
+		t.Fatal("expected IsError on gateway 4xx")
+	}
+	body := resultText(t, res)
+	if !strings.Contains(body, "400") {
+		t.Errorf("error result should mention status 400, got: %s", body)
+	}
+}
+
+func TestGatewayUnreachable_PropagatesAsIsError(t *testing.T) {
+	// Point at a non-listening port — connect will fail.
+	session := connect(t, "http://127.0.0.1:1") // reserved port
+
+	res := callTool(t, session, "list_datasets", listDatasetsArgs{})
+	if !res.IsError {
+		t.Fatal("expected IsError on unreachable gateway")
+	}
+}

go.mod

@@ -10,8 +10,12 @@ require (
 	github.com/aws/aws-sdk-go-v2/feature/s3/manager v1.22.16
 	github.com/aws/aws-sdk-go-v2/service/s3 v1.100.0
 	github.com/aws/smithy-go v1.25.0
+	github.com/coder/hnsw v0.6.1
+	github.com/duckdb/duckdb-go/v2 v2.10502.0
 	github.com/go-chi/chi/v5 v5.2.5
 	github.com/google/uuid v1.6.0
+	github.com/hashicorp/golang-lru/v2 v2.0.7
+	github.com/modelcontextprotocol/go-sdk v1.5.0
 	github.com/pelletier/go-toml/v2 v2.3.0
 )
 
@@ -33,27 +37,29 @@ require (
 	github.com/aws/aws-sdk-go-v2/service/sts v1.42.0 // indirect
 	github.com/cespare/xxhash/v2 v2.3.0 // indirect
 	github.com/chewxy/math32 v1.10.1 // indirect
-	github.com/coder/hnsw v0.6.1 // indirect
 	github.com/duckdb/duckdb-go-bindings v0.10502.0 // indirect
 	github.com/duckdb/duckdb-go-bindings/lib/darwin-amd64 v0.10502.0 // indirect
 	github.com/duckdb/duckdb-go-bindings/lib/darwin-arm64 v0.10502.0 // indirect
 	github.com/duckdb/duckdb-go-bindings/lib/linux-amd64 v0.10502.0 // indirect
 	github.com/duckdb/duckdb-go-bindings/lib/linux-arm64 v0.10502.0 // indirect
 	github.com/duckdb/duckdb-go-bindings/lib/windows-amd64 v0.10502.0 // indirect
-	github.com/duckdb/duckdb-go/v2 v2.10502.0 // indirect
 	github.com/go-viper/mapstructure/v2 v2.5.0 // indirect
 	github.com/goccy/go-json v0.10.6 // indirect
 	github.com/google/flatbuffers v25.12.19+incompatible // indirect
+	github.com/google/jsonschema-go v0.4.2 // indirect
 	github.com/google/renameio v1.0.1 // indirect
-	github.com/hashicorp/golang-lru/v2 v2.0.7 // indirect
 	github.com/klauspost/compress v1.18.5 // indirect
 	github.com/klauspost/cpuid/v2 v2.3.0 // indirect
 	github.com/pierrec/lz4/v4 v4.1.26 // indirect
+	github.com/segmentio/asm v1.1.3 // indirect
+	github.com/segmentio/encoding v0.5.4 // indirect
 	github.com/viterin/partial v1.1.0 // indirect
 	github.com/viterin/vek v0.4.2 // indirect
+	github.com/yosida95/uritemplate/v3 v3.0.2 // indirect
 	github.com/zeebo/xxh3 v1.1.0 // indirect
 	golang.org/x/exp v0.0.0-20260112195511-716be5621a96 // indirect
 	golang.org/x/net v0.52.0 // indirect
+	golang.org/x/oauth2 v0.35.0 // indirect
 	golang.org/x/sync v0.20.0 // indirect
 	golang.org/x/sys v0.43.0 // indirect
 	golang.org/x/text v0.35.0 // indirect

go.sum

@@ -74,12 +74,16 @@ github.com/go-viper/mapstructure/v2 v2.5.0 h1:vM5IJoUAy3d7zRSVtIwQgBj7BiWtMPfmPE
 github.com/go-viper/mapstructure/v2 v2.5.0/go.mod h1:oJDH3BJKyqBA2TXFhDsKDGDTlndYOZ6rGS0BRZIxGhM=
 github.com/goccy/go-json v0.10.6 h1:p8HrPJzOakx/mn/bQtjgNjdTcN+/S6FcG2CTtQOrHVU=
 github.com/goccy/go-json v0.10.6/go.mod h1:oq7eo15ShAhp70Anwd5lgX2pLfOS3QCiwU/PULtXL6M=
+github.com/golang-jwt/jwt/v5 v5.3.1 h1:kYf81DTWFe7t+1VvL7eS+jKFVWaUnK9cB1qbwn63YCY=
+github.com/golang-jwt/jwt/v5 v5.3.1/go.mod h1:fxCRLWMO43lRc8nhHWY6LGqRcf+1gQWArsqaEUEa5bE=
 github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek=
 github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps=
 github.com/google/flatbuffers v25.12.19+incompatible h1:haMV2JRRJCe1998HeW/p0X9UaMTK6SDo0ffLn2+DbLs=
 github.com/google/flatbuffers v25.12.19+incompatible/go.mod h1:1AeVuKshWv4vARoZatz6mlQ0JxURH0Kv5+zNeJKJCa8=
 github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/google/jsonschema-go v0.4.2 h1:tmrUohrwoLZZS/P3x7ex0WAVknEkBZM46iALbcqoRA8=
+github.com/google/jsonschema-go v0.4.2/go.mod h1:r5quNTdLOYEz95Ru18zA0ydNbBuYoo9tgaYcxEYhJVE=
 github.com/google/renameio v1.0.1 h1:Lh/jXZmvZxb0BBeSY5VKEfidcbcbenKjZFzM/q0fSeU=
 github.com/google/renameio v1.0.1/go.mod h1:t/HQoYBZSsWSNK35C6CO/TpPLDVWvxOHboWUAweKUpk=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
@@ -90,12 +94,18 @@ github.com/klauspost/compress v1.18.5 h1:/h1gH5Ce+VWNLSWqPzOVn6XBO+vJbCNGvjoaGBF
 github.com/klauspost/compress v1.18.5/go.mod h1:cwPg85FWrGar70rWktvGQj8/hthj3wpl0PGDogxkrSQ=
 github.com/klauspost/cpuid/v2 v2.3.0 h1:S4CRMLnYUhGeDFDqkGriYKdfoFlDnMtqTiI/sFzhA9Y=
 github.com/klauspost/cpuid/v2 v2.3.0/go.mod h1:hqwkgyIinND0mEev00jJYCxPNVRVXFQeu1XKlok6oO0=
+github.com/modelcontextprotocol/go-sdk v1.5.0 h1:CHU0FIX9kpueNkxuYtfYQn1Z0slhFzBZuq+x6IiblIU=
+github.com/modelcontextprotocol/go-sdk v1.5.0/go.mod h1:gggDIhoemhWs3BGkGwd1umzEXCEMMvAnhTrnbXJKKKA=
 github.com/pelletier/go-toml/v2 v2.3.0 h1:k59bC/lIZREW0/iVaQR8nDHxVq8OVlIzYCOJf421CaM=
 github.com/pelletier/go-toml/v2 v2.3.0/go.mod h1:2gIqNv+qfxSVS7cM2xJQKtLSTLUE9V8t9Stt+h56mCY=
 github.com/pierrec/lz4/v4 v4.1.26 h1:GrpZw1gZttORinvzBdXPUXATeqlJjqUG/D87TKMnhjY=
 github.com/pierrec/lz4/v4 v4.1.26/go.mod h1:EoQMVJgeeEOMsCqCzqFm2O0cJvljX2nGZjcRIPL34O4=
 github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
 github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/segmentio/asm v1.1.3 h1:WM03sfUOENvvKexOLp+pCqgb/WDjsi7EK8gIsICtzhc=
+github.com/segmentio/asm v1.1.3/go.mod h1:Ld3L4ZXGNcSLRg4JBsZ3//1+f/TjYl0Mzen/DQy1EJg=
+github.com/segmentio/encoding v0.5.4 h1:OW1VRern8Nw6ITAtwSZ7Idrl3MXCFwXHPgqESYfvNt0=
+github.com/segmentio/encoding v0.5.4/go.mod h1:HS1ZKa3kSN32ZHVZ7ZLPLXWvOVIiZtyJnO1gPH1sKt0=
 github.com/stretchr/objx v0.5.2 h1:xuMeJ0Sdp5ZMRXx/aWO6RZxdr3beISkG5/G/aIRr3pY=
 github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
 github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
@@ -106,6 +116,8 @@ github.com/viterin/vek v0.4.2 h1:Vyv04UjQT6gcjEFX82AS9ocgNbAJqsHviheIBdPlv5U=
 github.com/viterin/vek v0.4.2/go.mod h1:A4JRAe8OvbhdzBL5ofzjBS0J29FyUrf95tQogvtHHUc=
 github.com/xyproto/randomstring v1.0.5 h1:YtlWPoRdgMu3NZtP45drfy1GKoojuR7hmRcnhZqKjWU=
 github.com/xyproto/randomstring v1.0.5/go.mod h1:rgmS5DeNXLivK7YprL0pY+lTuhNQW3iGxZ18UQApw/E=
+github.com/yosida95/uritemplate/v3 v3.0.2 h1:Ed3Oyj9yrmi9087+NczuL5BwkIc4wvTb5zIM+UJPGz4=
+github.com/yosida95/uritemplate/v3 v3.0.2/go.mod h1:ILOh0sOhIJR3+L/8afwt/kE++YT040gmv5BQTMR2HP4=
 github.com/zeebo/assert v1.3.0 h1:g7C04CbJuIDKNPFHmsk4hwZDO5O+kntRxzaUoNXj+IQ=
 github.com/zeebo/assert v1.3.0/go.mod h1:Pq9JiuJQpG8JLJdtkwrJESF0Foym2/D9XMU5ciN/wJ0=
 github.com/zeebo/xxh3 v1.1.0 h1:s7DLGDK45Dyfg7++yxI0khrfwq9661w9EN78eP/UZVs=
@@ -126,12 +138,16 @@ golang.org/x/exp v0.0.0-20260112195511-716be5621a96 h1:Z/6YuSHTLOHfNFdb8zVZomZr7
 golang.org/x/exp v0.0.0-20260112195511-716be5621a96/go.mod h1:nzimsREAkjBCIEFtHiYkrJyT+2uy9YZJB7H1k68CXZU=
 golang.org/x/net v0.52.0 h1:He/TN1l0e4mmR3QqHMT2Xab3Aj3L9qjbhRm78/6jrW0=
 golang.org/x/net v0.52.0/go.mod h1:R1MAz7uMZxVMualyPXb+VaqGSa3LIaUqk0eEt3w36Sw=
+golang.org/x/oauth2 v0.35.0 h1:Mv2mzuHuZuY2+bkyWXIHMfhNdJAdwW3FuWeCPYN5GVQ=
+golang.org/x/oauth2 v0.35.0/go.mod h1:lzm5WQJQwKZ3nwavOZ3IS5Aulzxi68dUSgRHujetwEA=
 golang.org/x/sync v0.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4=
 golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
 golang.org/x/sys v0.43.0 h1:Rlag2XtaFTxp19wS8MXlJwTvoh8ArU6ezoyFsMyCTNI=
 golang.org/x/sys v0.43.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
 golang.org/x/text v0.35.0 h1:JOVx6vVDFokkpaq1AEptVzLTpDe9KGpj5tR4/X+ybL8=
 golang.org/x/text v0.35.0/go.mod h1:khi/HExzZJ2pGnjenulevKNX1W67CUy0AsXcNubPGCA=
+golang.org/x/tools v0.43.0 h1:12BdW9CeB3Z+J/I/wj34VMl8X+fEXBxVR90JeMX5E7s=
+golang.org/x/tools v0.43.0/go.mod h1:uHkMso649BX2cZK6+RpuIPXS3ho2hZo4FVwfoy1vIk0=
 gonum.org/v1/gonum v0.17.0 h1:VbpOemQlsSMrYmn7T2OUvQ4dqxQXU+ouZFQsZOx50z4=
 gonum.org/v1/gonum v0.17.0/go.mod h1:El3tOrEuMpv2UdMrbNlKEh9vd86bmQ6vqIcDwxEOc1E=
 google.golang.org/genproto/googleapis/rpc v0.0.0-20260120221211-b8f7ae30c516 h1:sNrWoksmOyF5bvJUcnmbeAmQi8baNhqg5IWaI3llQqU=