diff --git a/README.md b/README.md
index 15546c6..644a21c 100644
--- a/README.md
+++ b/README.md
@@ -96,14 +96,74 @@ npm install -g @anyproto/anytype-mcp
 
 ## Environment Variables
 
-| Variable                  | Default                         | Description                                                                                                                                                                         |
-| ------------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `OPENAPI_MCP_HEADERS`     | —                               | JSON object of headers forwarded to the Anytype API on every request. Required for auth: `{"Authorization":"Bearer <key>", "Anytype-Version":"2025-11-08"}`                         |
-| `ANYTYPE_API_BASE_URL`    | `http://127.0.0.1:31009`        | Anytype API base URL. Set to `http://localhost:31012` for `anytype-cli`.                                                                                                            |
-| `MCP_TRANSPORT`           | `stdio`                         | Transport mode. Set to `http` to enable the Streamable HTTP server.                                                                                                                 |
-| `MCP_HOST`                | `127.0.0.1`                     | Host to bind when `MCP_TRANSPORT=http`.                                                                                                                                             |
-| `MCP_PORT`                | `3666`                          | Port to listen on when `MCP_TRANSPORT=http`. Must be in range 1024–65535.                                                                                                           |
-| `MCP_PASSTHROUGH_HEADERS` | `authorization,anytype-version` | Comma-separated list of inbound HTTP header names (lowercase) forwarded from the MCP HTTP client to the Anytype API. Extend with caution — arbitrary headers must not be forwarded. |
+| Variable                  | Default                         | Description                                                                                                                                                                          |
+| ------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `OPENAPI_MCP_HEADERS`     | —                               | JSON object of headers forwarded to the Anytype API on every request. Required for auth: `{"Authorization":"Bearer <key>", "Anytype-Version":"2025-11-08"}`                          |
+| `ANYTYPE_API_BASE_URL`    | `http://127.0.0.1:31009`        | Anytype API base URL. Set to `http://localhost:31012` for `anytype-cli`.                                                                                                             |
+| `MCP_TRANSPORT`           | `stdio`                         | Transport mode. Set to `http` to enable the Streamable HTTP server.                                                                                                                  |
+| `MCP_HOST`                | `127.0.0.1`                     | Host to bind when `MCP_TRANSPORT=http`.                                                                                                                                              |
+| `MCP_PORT`                | `3666`                          | Port to listen on when `MCP_TRANSPORT=http`. Must be in range 1024–65535.                                                                                                            |
+| `MCP_PASSTHROUGH_HEADERS` | `authorization,anytype-version` | Comma-separated list of inbound HTTP header names (lowercase) forwarded from the MCP HTTP client to the Anytype API. Extend with caution — arbitrary headers must not be forwarded.  |
+| `MCP_INSTRUCTIONS`        | bundled `instructions.md`       | Instructions broadcast to MCP clients on connect. `false` disables; a string overrides with custom content; `{file:/path}` loads content from a file.                                |
+| `DISCOVERY_TOOL_CONFIG`   | —                               | JSON config for the `discover-spaces` tool. Accepts inline JSON or `{file:/path/to/config.json}`. Options: `ttlMs` (cache TTL ms, default 300000), `spaces` (per-space/type filter). |
+
+
+
+### discover-spaces Tool
+
+The `discover-spaces` tool returns a complete snapshot of your Anytype workspace — all spaces with their types, properties, tags, and select option IDs — in a single call. AI assistants use it to resolve IDs before creating or updating objects, eliminating the need to chain multiple list calls.
+
+#### Path narrowing
+
+Instead of fetching the full structure every time, you can request a sub-tree using bracket-notation path syntax:
+```
+discover-spaces(path='spaces["My Space"].tags')
+discover-spaces(path='spaces["My Space"].types["Task"].properties["Status"].select')
+```
+
+#### Filtering spaces and types
+
+By default all spaces and types are included.
+Use `DISCOVERY_TOOL_CONFIG` to limit the scope:
+```json
+{
+  "mcpServers": {
+    "anytype": {
+      "command": "npx",
+      "args": ["-y", "@anyproto/anytype-mcp"],
+      "env": {
+        "OPENAPI_MCP_HEADERS": "{\"Authorization\":\"Bearer <YOUR_API_KEY>\", \"Anytype-Version\":\"2025-11-08\"}",
+        "DISCOVERY_TOOL_CONFIG": "{\"spaces\":{\"Work\":{\"types\":{\"Task\":{},\"Project\":{}}},\"Personal\":{}}}"
+      }
+    }
+  }
+}
+```
+
+For non-trivial configs, use a file reference instead of an inline JSON string:
+```json
+"DISCOVERY_TOOL_CONFIG": "{file:path/to/discovery-config.json}"
+```
+
+`discovery-config.json`:
+```json
+{
+  "ttlMs": 300000,
+  "spaces": {
+    "Work": {
+      "types": {
+        "Task": {},
+        "Project": {}
+      }
+    },
+    "Personal": {}
+  }
+}
+```
+
+#### Cache
+
+Results are cached for 5 minutes by default. Set `ttlMs` in `DISCOVERY_TOOL_CONFIG` to adjust. The AI assistant will call `discover-spaces(force_refresh=true)` automatically after schema-mutating operations (creating or modifying a type, property, tag, or space).
 
 ### Custom API Base URL
 
diff --git a/eslint.config.js b/eslint.config.js
index 4cf8d6c..1fad586 100644
--- a/eslint.config.js
+++ b/eslint.config.js
@@ -27,6 +27,7 @@ export default [
       ...tseslint.configs.recommended.rules,
       "@typescript-eslint/no-explicit-any": "off",
       "@typescript-eslint/no-unused-vars": "off",
+      "no-undef": "off", // https://typescript-eslint.io/troubleshooting/faqs/eslint/#i-get-errors-from-the-no-undef-rule-about-global-variables-not-being-defined-even-though-there-are-no-typescript-errors
     },
   },
   {
diff --git a/instructions.md b/instructions.md
new file mode 100644
index 0000000..61d6712
--- /dev/null
+++ b/instructions.md
@@ -0,0 +1,75 @@
+# Anytype MCP Server — Instructions
+
+You are connected to an Anytype knowledge base via the **Anytype MCP server**.
+Follow these rules precisely to avoid data loss or API errors.
+
+## Session start — mandatory first step
+
+Call `discover-spaces` with no arguments **before any other tool call** in a new session.
+It returns every space, type, property, tag, and select-option ID you need.
+Cache this result mentally for the session — do not call it again unless you have performed a schema-mutating operation (creating or modifying a type, property, tag, or space).
+
+## ID resolution
+
+- **Never invent or guess IDs.** Every object, space, type, property, tag, and select option has an opaque content-addressed ID returned by `discover-spaces`.
+- **Tags are space-scoped.** The same tag name in two spaces has two different IDs. Always look up the ID from the correct space entry in the `discover-spaces` result.
+- **Select option IDs** are nested under `spaces["<Space>"].types["<Type>"].properties["<Property>"].select["<Option>"]`.
+- **Multi-Select option IDs** are nested under `spaces["<Space>"].types["<Type>"].properties["<Property>"].multi_select["<Option>"]`.
+- **Property keys** (used in mutation payloads) are at `.key` on each property entry, e.g. `"stage"`, `"company_name"`.
+
+Use bracket-notation `path` to narrow the result and avoid re-fetching:
+
+```
+discover-spaces(path='spaces["Career"].tags')
+discover-spaces(path='spaces["Career"].types["JobApplication"].properties["Stage"].select')
+```
+
+## Creating and updating objects
+
+Property payload shape: `{ key: <property key>, <format>: <value> }`
+
+Examples by format:
+
+| Format         | Payload                                            |
+| -------------- | -------------------------------------------------- |
+| `text`         | `{ key: "company_name", text: "Acme" }`            |
+| `url`          | `{ key: "vacancy_url", url: "https://..." }`       |
+| `number`       | `{ key: "salary", number: 120000 }`                |
+| `date`         | `{ key: "applied_date", date: "2026-03-13" }`      |
+| `select`       | `{ key: "stage", select: "<option-id>" }`          |
+| `multi_select` | `{ key: "tag", multi_select: ["<id1>", "<id2>"] }` |
+
+**Tag property** (`key: "tag"`) is valid on every object type. Use `multi_select` with tag IDs from the space's `tags` map.
+
+## Space routing
+
+When the user's intent determines the space, apply the default routing based on a space description.
+
+If the target space is ambiguous, ask before creating.
+
+## Mutation tagging — required on every write
+
+After every `create` or `update` operation, add the space's `mcp-modified` tag to the mutated object.
+Look up the ID from `spaces["<Space>"].tags["mcp-modified"]` in the `discover-spaces` result.
+
+## Schema mutation — when to force-refresh
+
+After any operation that creates or modifies a **type, property, tag, or space** (not ordinary objects), call `discover-spaces(force_refresh=true)` before continuing, so subsequent ID lookups reflect the updated schema.
+Do **not** call `force_refresh` speculatively — it is a network round-trip for every space.
+
+## Search
+
+`API-search-global` searches across all spaces. Prefer it for discovery when you do not know which space contains an object.
+
+## Error handling
+
+- If an API tool returns `{ "httpStatus": 404, ... }`, the object or resource does not exist — do not retry with the same arguments.
+- If an ID-dependent call fails, re-run `discover-spaces` (with `force_refresh=true` if schema may have changed) and re-resolve the ID before retrying.
+- Do not surface raw JSON error payloads to the user — summarise the failure and state what you will do next.
+
+## What not to do
+
+- Do not call `discover-spaces` more than once per session unless a schema mutation has occurred or a stale-ID error is encountered.
+- Do not call list-spaces, list-types, list-tags, or list-properties to resolve IDs — the `discover-spaces` result already contains everything needed.
+- Do not create objects without first confirming the correct space and type.
+- Do not perform bulk deletions, bulk moves, or any destructive operation on more than one object at a time without explicit per-object user confirmation.
\ No newline at end of file
diff --git a/scripts/__tests__/start-server.test.ts b/scripts/__tests__/start-server.test.ts
index 010f186..472334b 100644
--- a/scripts/__tests__/start-server.test.ts
+++ b/scripts/__tests__/start-server.test.ts
@@ -3,15 +3,19 @@ import fs from "node:fs";
 import path from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { loadOpenApiSpec, ValidationError } from "../../src/init-server";
+import { ensureAnytypeRunning } from "../../src/utils/anytype-launcher";
 import { overrideSpecPath } from "../../src/utils/base-url";
 
 // Reset specPathOverride after each test to avoid inter-test contamination
 afterEach(() => overrideSpecPath(undefined));
 
-// Mock fs and axios
+// Mock fs, axios, and the launcher
 vi.mock("node:fs");
 vi.mock("axios");
 vi.mock("@modelcontextprotocol/sdk/server/stdio.js");
+vi.mock("../../src/utils/anytype-launcher", () => ({
+  ensureAnytypeRunning: vi.fn().mockResolvedValue(false),
+}));
 
 // Create a mock Server class with proper prototype methods
 const mockSetRequestHandler = vi.fn();
@@ -96,7 +100,10 @@ describe("loadOpenApiSpec", () => {
 
       await loadOpenApiSpec();
 
-      expect(console.error).toHaveBeenCalledWith("Failed to read OpenAPI specification file:", expect.any(String));
+      expect(console.error).toHaveBeenCalledWith(
+        "Failed to read OpenAPI specification file from ./non-existent.json:",
+        "ENOENT: no such file or directory",
+      );
       expect(mockExit).toHaveBeenCalledWith(1);
     });
 
@@ -110,7 +117,10 @@ describe("loadOpenApiSpec", () => {
 
       await loadOpenApiSpec();
 
-      expect(console.error).toHaveBeenCalledWith("Failed to parse OpenAPI specification:", expect.any(String));
+      expect(console.error).toHaveBeenCalledWith(
+        "Failed to parse OpenAPI specification from ./invalid.json:",
+        expect.any(String),
+      );
       expect(mockExit).toHaveBeenCalledWith(1);
     });
 
@@ -136,7 +146,10 @@ describe("loadOpenApiSpec", () => {
 
       await loadOpenApiSpec();
 
-      expect(console.error).toHaveBeenCalledWith("Failed to parse OpenAPI specification:", expect.any(String));
+      expect(console.error).toHaveBeenCalledWith(
+        "Failed to parse OpenAPI specification from ./invalid.yaml:",
+        expect.any(String),
+      );
       expect(mockExit).toHaveBeenCalledWith(1);
     });
   });
@@ -163,7 +176,10 @@ describe("loadOpenApiSpec", () => {
 
       await loadOpenApiSpec();
 
-      expect(console.error).toHaveBeenCalledWith("Failed to fetch OpenAPI specification from URL:", "Network Error");
+      expect(console.error).toHaveBeenCalledWith(
+        "Failed to fetch OpenAPI specification from http://example.com/api-spec.json:",
+        "Network Error",
+      );
       expect(mockExit).toHaveBeenCalledWith(1);
     });
 
@@ -177,7 +193,10 @@ describe("loadOpenApiSpec", () => {
 
       await loadOpenApiSpec();
 
-      expect(console.error).toHaveBeenCalledWith("Failed to parse OpenAPI specification:", expect.any(String));
+      expect(console.error).toHaveBeenCalledWith(
+        "Failed to parse OpenAPI specification from http://example.com/api-spec.json:",
+        expect.any(String),
+      );
       expect(mockExit).toHaveBeenCalledWith(1);
     });
 
@@ -193,6 +212,49 @@ describe("loadOpenApiSpec", () => {
       expect(axios.get).toHaveBeenCalledWith("http://example.com/api-spec.yaml");
     });
   });
+
+  describe("ECONNREFUSED auto-launch retry", () => {
+    const econnRefused = Object.assign(new Error("connect ECONNREFUSED 127.0.0.1:31009"), { code: "ECONNREFUSED" });
+
+    it("launches Anytype and retries when ECONNREFUSED on a local URL", async () => {
+      vi.mocked(ensureAnytypeRunning).mockResolvedValue(true);
+      // First call throws, second succeeds after launch
+      vi.mocked(axios.get).mockRejectedValueOnce(econnRefused).mockResolvedValueOnce({ data: validOpenApiSpec });
+      overrideSpecPath("http://127.0.0.1:31009/docs/openapi.json");
+
+      const result = await loadOpenApiSpec();
+
+      expect(ensureAnytypeRunning).toHaveBeenCalledWith("http://127.0.0.1:31009");
+      expect(result).toEqual(validOpenApiSpec);
+    });
+
+    it("exits with 1 when ECONNREFUSED and ensureAnytypeRunning returns false", async () => {
+      vi.mocked(ensureAnytypeRunning).mockResolvedValue(false);
+      vi.mocked(axios.get).mockRejectedValueOnce(econnRefused);
+      overrideSpecPath("http://127.0.0.1:31009/docs/openapi.json");
+
+      const mockExit = vi.spyOn(process, "exit").mockImplementation((() => {}) as any);
+      await loadOpenApiSpec();
+
+      expect(console.error).toHaveBeenCalledWith(expect.stringContaining("Cannot connect to Anytype API"));
+      expect(mockExit).toHaveBeenCalledWith(1);
+    });
+
+    it("exits with 1 when Anytype launches but API is still unreachable on retry", async () => {
+      vi.mocked(ensureAnytypeRunning).mockResolvedValue(true);
+      vi.mocked(axios.get).mockRejectedValue(econnRefused); // both calls fail
+      overrideSpecPath("http://127.0.0.1:31009/docs/openapi.json");
+
+      const mockExit = vi.spyOn(process, "exit").mockImplementation((() => {}) as any);
+      await loadOpenApiSpec();
+
+      expect(console.error).toHaveBeenCalledWith(
+        "Failed to parse OpenAPI specification from http://127.0.0.1:31009/docs/openapi.json:",
+        expect.any(String),
+      );
+      expect(mockExit).toHaveBeenCalledWith(1);
+    });
+  });
 });
 
 describe("main", () => {
diff --git a/scripts/build-cli.js b/scripts/build-cli.js
index fe2508c..62ab638 100644
--- a/scripts/build-cli.js
+++ b/scripts/build-cli.js
@@ -1,11 +1,13 @@
 import * as esbuild from "esbuild";
+import { readFileSync } from "fs";
 import { chmod } from "fs/promises";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
-
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
 async function build() {
+  const instructions = readFileSync(join(__dirname, "../instructions.md"), "utf8");
+
   await esbuild.build({
     entryPoints: [join(__dirname, "start-server.ts")],
     bundle: true,
@@ -18,6 +20,9 @@ async function build() {
       js: "#!/usr/bin/env node\nimport { createRequire } from 'module';const require = createRequire(import.meta.url);", // see https://github.com/evanw/esbuild/pull/2067
     },
     external: ["util"],
+    define: {
+      __BUNDLED_INSTRUCTIONS__: JSON.stringify(instructions),
+    },
   });
 
   // Make the output file executable
diff --git a/src/client/__tests__/http-client.test.ts b/src/client/__tests__/http-client.test.ts
index 6a5be6e..307421d 100644
--- a/src/client/__tests__/http-client.test.ts
+++ b/src/client/__tests__/http-client.test.ts
@@ -3,7 +3,7 @@ import { Headers } from "node-fetch";
 import OpenAPIClientAxios from "openapi-client-axios";
 import { OpenAPIV3 } from "openapi-types";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { HttpClient } from "../http-client";
+import { HttpClient, HttpClientConnectionError } from "../http-client";
 
 function makeAxiosError(status: number, statusText: string, data: any, headers: Record<string, string> = {}) {
   const err = new axios.AxiosError(statusText);
@@ -533,4 +533,82 @@ describe("HttpClient", () => {
     // Additional check to ensure headers are correctly processed
     expect(response.headers.get("content-type")).toBe("application/json");
   });
+
+  // ─── HttpClientConnectionError ────────────────────────────────────────────
+
+  describe("connection errors", () => {
+    function makeConnectionError(code: string) {
+      const err = new axios.AxiosError(code);
+      err.code = code;
+      // No `response` — transport-level failure
+      err.isAxiosError = true;
+      return err;
+    }
+
+    it.each([["ECONNREFUSED"], ["ENOTFOUND"], ["ETIMEDOUT"]])(
+      "throws HttpClientConnectionError for %s",
+      async (code) => {
+        const mockAxiosInstance = {
+          testOperation: vi.fn().mockRejectedValue(makeConnectionError(code)),
+        };
+        const MockClient = vi.fn(function (this: any) {
+          this.init = vi.fn().mockResolvedValue(mockAxiosInstance);
+          this.axiosConfigDefaults = { baseURL: "http://127.0.0.1:31009" };
+          return this;
+        });
+        vi.mocked(OpenAPIClientAxios).mockImplementation(MockClient as any);
+
+        const client = new HttpClient(mockConfig, mockOpenApiSpec);
+        const operation = mockOpenApiSpec.paths["/test"]?.post as OpenAPIV3.OperationObject & {
+          method: string;
+          path: string;
+        };
+
+        await expect(client.executeOperation(operation, {})).rejects.toThrow(HttpClientConnectionError);
+      },
+    );
+
+    it("error message includes the base URL", async () => {
+      const mockAxiosInstance = {
+        testOperation: vi.fn().mockRejectedValue(makeConnectionError("ECONNREFUSED")),
+      };
+      const MockClient = vi.fn(function (this: any) {
+        this.init = vi.fn().mockResolvedValue(mockAxiosInstance);
+        this.axiosConfigDefaults = { baseURL: "http://127.0.0.1:31009" };
+        return this;
+      });
+      vi.mocked(OpenAPIClientAxios).mockImplementation(MockClient as any);
+
+      const client = new HttpClient({ baseUrl: "http://127.0.0.1:31009", headers: {} }, mockOpenApiSpec);
+      const operation = mockOpenApiSpec.paths["/test"]?.post as OpenAPIV3.OperationObject & {
+        method: string;
+        path: string;
+      };
+
+      const err = await client.executeOperation(operation, {}).catch((e) => e);
+      expect(err).toBeInstanceOf(HttpClientConnectionError);
+      expect(err.message).toMatch(/127\.0\.0\.1/);
+    });
+
+    it("does NOT throw HttpClientConnectionError when the server returns an HTTP error status", async () => {
+      // An HTTP 503 has a response object — must become HttpClientError, not connection error.
+      const httpErr = makeAxiosError(503, "Service Unavailable", { message: "down" });
+      const mockAxiosInstance = { testOperation: vi.fn().mockRejectedValue(httpErr) };
+      const MockClient = vi.fn(function (this: any) {
+        this.init = vi.fn().mockResolvedValue(mockAxiosInstance);
+        return this;
+      });
+      vi.mocked(OpenAPIClientAxios).mockImplementation(MockClient as any);
+
+      const client = new HttpClient(mockConfig, mockOpenApiSpec);
+      const operation = mockOpenApiSpec.paths["/test"]?.post as OpenAPIV3.OperationObject & {
+        method: string;
+        path: string;
+      };
+
+      const err = await client.executeOperation(operation, {}).catch((e) => e);
+      expect(err).not.toBeInstanceOf(HttpClientConnectionError);
+      expect(err.status).toBe(503);
+    });
+  });
 });
diff --git a/src/client/http-client.ts b/src/client/http-client.ts
index 2c44cdb..5c17010 100644
--- a/src/client/http-client.ts
+++ b/src/client/http-client.ts
@@ -26,6 +26,18 @@ export class HttpClientError extends Error {
   }
 }
 
+/** Thrown when the upstream API is unreachable (ECONNREFUSED, ENOTFOUND, ETIMEDOUT, etc.). */
+export class HttpClientConnectionError extends Error {
+  constructor(
+    message: string,
+    public readonly baseUrl: string,
+    public readonly cause?: unknown,
+  ) {
+    super(message);
+    this.name = "HttpClientConnectionError";
+  }
+}
+
 export class HttpClient {
   private api: Promise<AxiosInstance>;
   private client: OpenAPIClientAxios;
@@ -213,6 +225,15 @@ export class HttpClient {
           headers,
         );
       }
+      if (axios.isAxiosError(error) && !error.response) {
+        // No response — transport-level failure (ECONNREFUSED, ENOTFOUND, ETIMEDOUT, …)
+        const baseUrl = (this.client as any).axiosConfigDefaults?.baseURL ?? "unknown";
+        throw new HttpClientConnectionError(
+          `Cannot connect to Anytype API at ${baseUrl}: ${error.message}`,
+          baseUrl,
+          error,
+        );
+      }
       throw error;
     }
   }
diff --git a/src/global.d.ts b/src/global.d.ts
new file mode 100644
index 0000000..61faf5d
--- /dev/null
+++ b/src/global.d.ts
@@ -0,0 +1 @@
+declare const __BUNDLED_INSTRUCTIONS__: string;
diff --git a/src/init-server.ts b/src/init-server.ts
index 8339eef..213947c 100644
--- a/src/init-server.ts
+++ b/src/init-server.ts
@@ -5,7 +5,8 @@ import path from "node:path";
 import { OpenAPIV3 } from "openapi-types";
 import { startHttpTransport } from "./mcp/http-transport";
 import { MCPProxy } from "./mcp/proxy";
-import { resolveSpecPath } from "./utils/base-url";
+import { ensureAnytypeRunning } from "./utils/anytype-launcher";
+import { DEFAULT_BASE_URL, resolveSpecPath } from "./utils/base-url";
 import { getConfig } from "./utils/config";
 
 export class ValidationError extends Error {
@@ -20,23 +21,39 @@ export async function loadOpenApiSpec(): Promise<OpenAPIV3.Document> {
   let rawSpec: string | undefined;
 
   if (finalSpec.startsWith("http://") || finalSpec.startsWith("https://")) {
-    try {
+    const fetchSpec = async () => {
       const response = await axios.get(finalSpec);
-      rawSpec = typeof response.data === "string" ? response.data : JSON.stringify(response.data);
+      return typeof response.data === "string" ? response.data : JSON.stringify(response.data);
+    };
+
+    try {
+      rawSpec = await fetchSpec();
     } catch (error: any) {
       if (error.code === "ECONNREFUSED") {
-        console.error("Can't connect to API. Please ensure Anytype is running and reachable.");
+        const baseUrl = getConfig().httpClient.baseUrl ?? DEFAULT_BASE_URL;
+        const launched = await ensureAnytypeRunning(baseUrl);
+        if (launched) {
+          try {
+            rawSpec = await fetchSpec();
+          } catch (retryError: any) {
+            console.error(`Anytype started but API is still unreachable at ${baseUrl}:`, retryError.message);
+            process.exit(1);
+          }
+        } else {
+          console.error(`Cannot connect to Anytype API at ${baseUrl}. Please ensure the Anytype app is running.`);
+          process.exit(1);
+        }
+      } else {
+        console.error(`Failed to fetch OpenAPI specification from ${finalSpec}:`, error.message);
         process.exit(1);
       }
-      console.error("Failed to fetch OpenAPI specification from URL:", error.message);
-      process.exit(1);
     }
   } else {
     const filePath = path.resolve(process.cwd(), finalSpec);
     try {
       rawSpec = fs.readFileSync(filePath, "utf-8");
     } catch (error: any) {
-      console.error("Failed to read OpenAPI specification file:", error.message || String(error));
+      console.error(`Failed to read OpenAPI specification file from ${finalSpec}:`, error.message || String(error));
       process.exit(1);
     }
   }
@@ -44,7 +61,7 @@ export async function loadOpenApiSpec(): Promise<OpenAPIV3.Document> {
   try {
     return JSON.parse(rawSpec) as OpenAPIV3.Document;
   } catch (error: any) {
-    console.error("Failed to parse OpenAPI specification:", error.message);
+    console.error(`Failed to parse OpenAPI specification from ${finalSpec}:`, error.message);
     process.exit(1);
   }
 }
diff --git a/src/mcp/__tests__/proxy.test.ts b/src/mcp/__tests__/proxy.test.ts
index f56656c..fff16ff 100644
--- a/src/mcp/__tests__/proxy.test.ts
+++ b/src/mcp/__tests__/proxy.test.ts
@@ -2,11 +2,18 @@ import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 import { Headers } from "node-fetch";
 import { OpenAPIV3 } from "openapi-types";
 import { beforeEach, describe, expect, it, vi } from "vitest";
-import { HttpClient } from "../../client/http-client";
+import { HttpClient, HttpClientConnectionError } from "../../client/http-client";
 import { MCPProxy } from "../proxy";
 
-// Mock the dependencies
-vi.mock("../../client/http-client");
+// Keep real error classes (needed for instanceof checks in proxy.ts) but mock the HttpClient constructor.
+vi.mock("../../client/http-client", async (importOriginal) => {
+  const real = await importOriginal<typeof import("../../client/http-client")>();
+  const MockHttpClient = vi.fn(function (this: any) {
+    this.executeOperation = vi.fn();
+    this.withHeaders = vi.fn();
+  });
+  return { ...real, HttpClient: MockHttpClient };
+});
 vi.mock("@modelcontextprotocol/sdk/server/index.js");
 
 describe("MCPProxy", () => {
@@ -35,6 +42,10 @@ describe("MCPProxy", () => {
     ...overrides,
   });
 
+  /** Returns the executeOperation mock from the HttpClient instance created by the last MCPProxy constructor call. */
+  const getMockExecuteOperation = () =>
+    vi.mocked(HttpClient).mock.results.at(-1)?.value.executeOperation as ReturnType<typeof vi.fn>;
+
   beforeEach(() => {
     vi.clearAllMocks();
     mockOpenApiSpec = createMockOpenApiSpec();
@@ -77,7 +88,7 @@ describe("MCPProxy", () => {
     };
 
     it("should execute operation and return formatted response", async () => {
-      (HttpClient.prototype.executeOperation as ReturnType<typeof vi.fn>).mockResolvedValue(mockSuccessResponse);
+      getMockExecuteOperation().mockResolvedValue(mockSuccessResponse);
 
       (proxy as any).openApiLookup = {
         "API-getTest": {
@@ -104,8 +115,34 @@ describe("MCPProxy", () => {
       );
     });
 
+    it("should return connection_failed error content when Anytype is unreachable", async () => {
+      const connError = new HttpClientConnectionError(
+        "Cannot connect to Anytype API at http://127.0.0.1:31009: connect ECONNREFUSED",
+        "http://127.0.0.1:31009",
+      );
+      getMockExecuteOperation().mockRejectedValue(connError);
+
+      (proxy as any).openApiLookup = {
+        "API-getTest": {
+          operationId: "getTest",
+          responses: { "200": { description: "Success" } },
+          method: "get",
+          path: "/test",
+        },
+      };
+
+      const [, callToolHandler] = getHandlers(proxy);
+      const result = await callToolHandler({ params: { name: "API-getTest", arguments: {} } });
+
+      expect(result.isError).toBe(true);
+      const payload = JSON.parse(result.content[0].text);
+      expect(payload.error).toBe("connection_failed");
+      expect(payload.message).toContain("127.0.0.1:31009");
+      expect(payload.hint).toMatch(/Anytype/i);
+    });
+
     it("should handle tool names exceeding 64 characters", async () => {
-      (HttpClient.prototype.executeOperation as ReturnType<typeof vi.fn>).mockResolvedValue(mockSuccessResponse);
+      getMockExecuteOperation().mockResolvedValue(mockSuccessResponse);
 
       const longToolName = "a".repeat(65);
       const truncatedToolName = longToolName.slice(0, 64);
diff --git a/src/mcp/http-transport.ts b/src/mcp/http-transport.ts
index 39d070d..9eeb386 100644
--- a/src/mcp/http-transport.ts
+++ b/src/mcp/http-transport.ts
@@ -25,7 +25,6 @@ export async function startHttpTransport(
 ): Promise<void> {
   const server = http.createServer(async (req, res) => {
     const { method, url } = req;
-    console.error(`[http] ${method} ${url}`);
 
     applyCorsHeaders(req, res);
 
diff --git a/src/mcp/proxy.ts b/src/mcp/proxy.ts
index ef5f242..f55440d 100644
--- a/src/mcp/proxy.ts
+++ b/src/mcp/proxy.ts
@@ -4,9 +4,16 @@ import { CallToolRequestSchema, ListToolsRequestSchema, Tool } from "@modelconte
 import { Headers } from "node-fetch";
 import { OpenAPIV3 } from "openapi-types";
 import pkg from "../../package.json";
-import { HttpClient, HttpClientError } from "../client/http-client";
+import { HttpClient, HttpClientConnectionError, HttpClientError } from "../client/http-client";
 import { OpenAPIToMCPConverter, type ToolMethod } from "../openapi/parser";
 import { getConfig } from "../utils/config";
+import { resolveInstructions } from "../utils/resolveInstructions";
+import {
+  DISCOVER_SPACES_TOOL_NAME,
+  discoverSpacesTool,
+  makeDiscoverSpacesHandler,
+  type DiscoverSpacesParams,
+} from "./tools/discovery";
 
 type PathItemObject = OpenAPIV3.PathItemObject & {
   get?: OpenAPIV3.OperationObject;
@@ -26,16 +33,22 @@ export class MCPProxy {
     serverInfo: ConstructorParameters<typeof Server>[0];
     serverOptions: NonNullable<ConstructorParameters<typeof Server>[1]>;
   };
+  private discoverSpaces: (params: DiscoverSpacesParams) => Promise<{ content: Array<{ type: "text"; text: string }> }>;
 
   constructor(name: string, openApiSpec: OpenAPIV3.Document) {
     this.state = {
       toolsLogged: false,
       serverInfo: { name, version: pkg.version, description: `Anytype API proxy (spec v${openApiSpec.info.version})` },
-      serverOptions: { capabilities: { tools: {} } },
+      serverOptions: {
+        capabilities: { tools: {} },
+        instructions: resolveInstructions(getConfig().instructions),
+      },
     };
     this.server = new Server(this.state.serverInfo, this.state.serverOptions);
     this.httpClient = new HttpClient(getConfig().httpClient, openApiSpec);
 
+    this.discoverSpaces = makeDiscoverSpacesHandler(getConfig().httpClient, getConfig().tools?.discoverSpaces);
+
     // Convert OpenAPI spec to MCP tools
     const converter = new OpenAPIToMCPConverter(openApiSpec, {
       skipToolNamePrefix: true,
@@ -66,7 +79,7 @@ export class MCPProxy {
         });
       });
 
-      const tools: Tool[] = [];
+      const tools: Tool[] = [discoverSpacesTool];
 
       toolsByMethodName.forEach((bucket) => {
         const isCollision = bucket.length > 1;
@@ -89,15 +102,14 @@ export class MCPProxy {
     this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
       const { name, arguments: params } = request.params;
 
-      // Find the operation in OpenAPI spec
-      const operation = this.findOperation(name);
+      console.error(`[tool] ${name}(${JSON.stringify(params)})`);
 
-      if (!this.state.toolsLogged) {
-        const toolNames = Object.keys(this.openApiLookup);
-        console.error(`tools (count: ${toolNames.length}): ${toolNames.join(", ")}`);
-        this.state.toolsLogged = true;
+      if (name === DISCOVER_SPACES_TOOL_NAME) {
+        return this.discoverSpaces(params as DiscoverSpacesParams);
       }
 
+      // Find the operation in OpenAPI spec
+      const operation = this.findOperation(name);
       if (!operation) {
         throw new Error(`Method ${name} not found`);
       }
@@ -131,6 +143,23 @@ export class MCPProxy {
           };
         }
 
+        if (error instanceof HttpClientConnectionError) {
+          console.error(`Connection error in "${name}" tool call:`, error.message);
+          return {
+            isError: true,
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify({
+                  error: "connection_failed",
+                  message: error.message,
+                  hint: "Ensure the Anytype app is running and reachable.",
+                }),
+              },
+            ],
+          };
+        }
+
         console.error(`Unexpected error in "${name}" tool call`, error);
 
         // don’t leak internals or secrets, throw opaque error
@@ -140,7 +169,14 @@ export class MCPProxy {
   }
 
   private findOperation(operationId: string): (OpenAPIV3.OperationObject & { method: string; path: string }) | null {
-    return this.openApiLookup[operationId] ?? null;
+    const result = this.openApiLookup[operationId] ?? null;
+    if (!result) {
+      console.error(
+        `[findOperation] miss: "${operationId}". Available keys (${Object.keys(this.openApiLookup).length}):`,
+        Object.keys(this.openApiLookup).join(", "),
+      );
+    }
+    return result;
   }
 
   private getContentType(headers: Headers): "text" | "image" | "binary" {
@@ -180,6 +216,7 @@ export class MCPProxy {
     instance.httpClient = requestHeaders ? this.httpClient.withHeaders(requestHeaders) : this.httpClient;
     instance.tools = this.tools;
     instance.openApiLookup = this.openApiLookup;
+    instance.discoverSpaces = this.discoverSpaces; // shared — handler closes over its own cache
     instance.setupHandlers();
     return instance;
   }
diff --git a/src/mcp/tools/__tests__/discovery.schema.test.ts b/src/mcp/tools/__tests__/discovery.schema.test.ts
new file mode 100644
index 0000000..0b3c2e3
--- /dev/null
+++ b/src/mcp/tools/__tests__/discovery.schema.test.ts
@@ -0,0 +1,95 @@
+// src/mcp/tools/__tests__/discovery.schema.test.ts
+
+import { describe, expect, it } from "vitest";
+import { DiscoveryToolConfigSchema } from "../discovery.schema";
+
+describe("DiscoveryToolConfigSchema", () => {
+  // ─── valid inputs ──────────────────────────────────────────────────────────
+
+  it("accepts empty object", () => {
+    expect(DiscoveryToolConfigSchema.parse({})).toEqual({
+      ttlMs: undefined,
+      spaces: undefined,
+    });
+  });
+
+  it("accepts ttlMs only", () => {
+    expect(DiscoveryToolConfigSchema.parse({ ttlMs: 60000 })).toMatchObject({
+      ttlMs: 60000,
+    });
+  });
+
+  it("accepts full spaces filter", () => {
+    const result = DiscoveryToolConfigSchema.parse({
+      spaces: {
+        Attic: { types: { Daily: {}, Note: {} } },
+        Career: { types: { JobApplication: {} } },
+      },
+    });
+    expect(result.spaces).toEqual({
+      Attic: { types: { Daily: {}, Note: {} } },
+      Career: { types: { JobApplication: {} } },
+    });
+  });
+
+  it("accepts space entry with no types filter", () => {
+    const result = DiscoveryToolConfigSchema.parse({
+      spaces: { Attic: {} },
+    });
+    expect(result.spaces).toEqual({ Attic: { types: undefined } });
+  });
+
+  // ─── transform: unknown keys are stripped from output ─────────────────────
+
+  it("strips unknown top-level keys from output after validation", () => {
+    // Must fail validation — but if we bypassed superRefine, strip would work.
+    // Test the transform directly by checking a valid-but-extended object would
+    // not leak unknown keys — we verify via the error path instead (see below).
+    // This test documents intent: output only contains {ttlMs, spaces}.
+    const result = DiscoveryToolConfigSchema.parse({ ttlMs: 1000, spaces: {} });
+    expect(Object.keys(result)).toEqual(["ttlMs", "spaces"]);
+  });
+
+  // ─── superRefine: unrecognized keys ───────────────────────────────────────
+
+  it("rejects bare spaces map (common mistake: missing {spaces:} wrapper)", () => {
+    const result = DiscoveryToolConfigSchema.safeParse({
+      Attic: { types: { Daily: {} } },
+      Career: {},
+    });
+    expect(result.success).toBe(false);
+    expect(result.error?.issues[0].message).toMatch(/unrecognized key/i);
+    expect(result.error?.issues[0].message).toContain("DISCOVERY_TOOL_CONFIG");
+    expect(result.error?.issues[0].message).toContain('"Attic"');
+  });
+
+  it("error message includes expected shape hint", () => {
+    const result = DiscoveryToolConfigSchema.safeParse({ space: {} });
+    expect(result.error?.issues[0].message).toContain("Expected shape:");
+    expect(result.error?.issues[0].message).toContain('"spaces"');
+  });
+
+  it('rejects typo "space" with key named in error', () => {
+    const result = DiscoveryToolConfigSchema.safeParse({ space: {} });
+    expect(result.success).toBe(false);
+    expect(result.error?.issues[0].message).toContain('"space"');
+  });
+
+  // ─── field validation ─────────────────────────────────────────────────────
+
+  it("rejects negative ttlMs", () => {
+    expect(() => DiscoveryToolConfigSchema.parse({ ttlMs: -1 })).toThrow();
+  });
+
+  it("rejects zero ttlMs", () => {
+    expect(() => DiscoveryToolConfigSchema.parse({ ttlMs: 0 })).toThrow();
+  });
+
+  it("rejects non-integer ttlMs", () => {
+    expect(() => DiscoveryToolConfigSchema.parse({ ttlMs: 1.5 })).toThrow();
+  });
+
+  it("rejects string ttlMs", () => {
+    expect(() => DiscoveryToolConfigSchema.parse({ ttlMs: "60000" })).toThrow();
+  });
+});
diff --git a/src/mcp/tools/__tests__/discovery.test.ts b/src/mcp/tools/__tests__/discovery.test.ts
new file mode 100644
index 0000000..89bb92d
--- /dev/null
+++ b/src/mcp/tools/__tests__/discovery.test.ts
@@ -0,0 +1,297 @@
+import axios from "axios";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { DiscoveryResult } from "../discovery";
+import { fetchDiscovery, makeDiscoverSpacesHandler, resolvePath } from "../discovery";
+
+// ---------------------------------------------------------------------------
+// resolvePath
+// ---------------------------------------------------------------------------
+
+describe("resolvePath", () => {
+  const data = {
+    spaces: {
+      Career: {
+        id: "career-id",
+        tags: { react: "tag-1", "~test~": "tag-2" },
+        types: {
+          JobApplication: {
+            id: "type-id",
+            key: "job_application",
+            properties: {
+              Stage: {
+                id: "prop-id",
+                key: "stage",
+                format: "select",
+                select: { New: "opt-1", Rejected: "opt-2" },
+              },
+            },
+          },
+        },
+      },
+    },
+    fetched_at: "2026-01-01T00:00:00.000Z",
+  };
+
+  it("returns full data when path is omitted", () => {
+    expect(resolvePath(data, "spaces")).toEqual(data.spaces);
+  });
+
+  it("resolves dot segment", () => {
+    expect(resolvePath(data, "fetched_at")).toBe("2026-01-01T00:00:00.000Z");
+  });
+
+  it("resolves bracket notation", () => {
+    expect(resolvePath(data, 'spaces["Career"].id')).toBe("career-id");
+  });
+
+  it("resolves nested bracket notation", () => {
+    expect(resolvePath(data, 'spaces["Career"].tags["~test~"]')).toBe("tag-2");
+  });
+
+  it("resolves deep path", () => {
+    expect(resolvePath(data, 'spaces["Career"].types["JobApplication"].properties["Stage"].select["New"]')).toBe(
+      "opt-1",
+    );
+  });
+
+  it("returns undefined for missing key", () => {
+    expect(resolvePath(data, 'spaces["Attic"].tags')).toBeUndefined();
+  });
+
+  it("returns undefined when traversing into a non-object", () => {
+    expect(resolvePath(data, "fetched_at.nested")).toBeUndefined();
+  });
+
+  it("handles keys with dots in bracket notation", () => {
+    const d = { props: { "salary_(initial)": "id-1" } };
+    expect(resolvePath(d, 'props["salary_(initial)"]')).toBe("id-1");
+  });
+
+  it("handles keys with slashes in bracket notation", () => {
+    const d = { props: { "any/type": "id-2" } };
+    expect(resolvePath(d, 'props["any/type"]')).toBe("id-2");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// fetchDiscovery (axios mocked)
+// ---------------------------------------------------------------------------
+
+vi.mock("axios", async (importOriginal) => {
+  const actual = await importOriginal<typeof axios>();
+  return {
+    ...actual,
+    default: {
+      ...actual.defaults,
+      create: vi.fn(),
+    },
+  };
+});
+
+const mockGet = vi.fn();
+
+function makeSpace(id: string, name: string, description?: string) {
+  return { id, name, ...(description ? { description } : {}) };
+}
+
+function setupAxiosMock() {
+  vi.mocked(axios.create).mockReturnValue({ get: mockGet } as any);
+}
+
+const FIXTURES = {
+  spaces: [makeSpace("space-career", "Career", "Job hunting")],
+  properties: [{ id: "prop-tag", key: "tag", format: "multi_select" }],
+  tags: [
+    { id: "tag-react", name: "react" },
+    { id: "tag-mcp", name: "mcp-modified" },
+  ],
+  types: [
+    {
+      id: "type-ja",
+      key: "job_application",
+      name: "JobApplication",
+      properties: [
+        { id: "prop-stage", key: "stage", name: "Stage", format: "select" },
+        { id: "prop-name", key: "company_name", name: "Company Name", format: "text" },
+        // skipped
+        { id: "prop-tag2", key: "tag", name: "Tag", format: "multi_select" },
+        { id: "prop-bl", key: "backlinks", name: "Backlinks", format: "multi_select" },
+      ],
+    },
+  ],
+  stageTags: [
+    { id: "opt-new", name: "New" },
+    { id: "opt-rejected", name: "Rejected" },
+  ],
+};
+
+function mockGetSequence(...responses: any[]) {
+  responses.forEach((r) => {
+    mockGet.mockResolvedValueOnce({ data: { data: r } });
+  });
+}
+
+describe("fetchDiscovery", () => {
+  beforeEach(() => {
+    setupAxiosMock();
+    mockGet.mockReset();
+  });
+
+  it("fetches all spaces and resolves tags and types", async () => {
+    mockGetSequence(
+      FIXTURES.spaces, // GET /v1/spaces
+      FIXTURES.properties, // GET /v1/spaces/space-career/properties
+      FIXTURES.tags, // GET /v1/spaces/space-career/properties/prop-tag/tags (space tags)
+      FIXTURES.types, // GET /v1/spaces/space-career/types
+      FIXTURES.stageTags, // GET /v1/spaces/space-career/properties/prop-stage/tags
+    );
+
+    const result = await fetchDiscovery({ headers: {} });
+
+    expect(result.spaces["Career"]).toMatchObject({
+      id: "space-career",
+      description: "Job hunting",
+      tags: { react: "tag-react", "mcp-modified": "tag-mcp" },
+      types: {
+        JobApplication: {
+          id: "type-ja",
+          key: "job_application",
+          properties: {
+            Stage: {
+              id: "prop-stage",
+              key: "stage",
+              format: "select",
+              select: { New: "opt-new", Rejected: "opt-rejected" },
+            },
+            "Company Name": { id: "prop-name", key: "company_name", format: "text" },
+          },
+        },
+      },
+    });
+  });
+
+  it("skips tag and backlinks properties", async () => {
+    mockGetSequence(FIXTURES.spaces, FIXTURES.properties, FIXTURES.tags, FIXTURES.types, FIXTURES.stageTags);
+
+    const result = await fetchDiscovery({ headers: {} });
+    const props = result.spaces["Career"]!.types["JobApplication"]!.properties;
+    expect(props["Tag"]).toBeUndefined();
+    expect(props["Backlinks"]).toBeUndefined();
+  });
+
+  it("filters spaces by config", async () => {
+    mockGetSequence(
+      [makeSpace("space-career", "Career"), makeSpace("space-attic", "Attic")],
+      FIXTURES.properties,
+      FIXTURES.tags,
+      FIXTURES.types,
+      FIXTURES.stageTags,
+    );
+
+    const result = await fetchDiscovery({ headers: {} }, { Career: {} });
+    expect(Object.keys(result.spaces)).toEqual(["Career"]);
+  });
+
+  it("filters types by config", async () => {
+    const allTypes = [...FIXTURES.types, { id: "type-page", key: "page", name: "Page", properties: [] }];
+
+    mockGetSequence(FIXTURES.spaces, FIXTURES.properties, FIXTURES.tags, allTypes, FIXTURES.stageTags);
+
+    const result = await fetchDiscovery({ headers: {} }, { Career: { types: { JobApplication: {} } } });
+    const types = result.spaces["Career"]!.types;
+    expect(Object.keys(types)).toEqual(["JobApplication"]);
+  });
+
+  it("throws if tag property is missing", async () => {
+    mockGetSequence(
+      FIXTURES.spaces,
+      [], // no properties → tag prop not found
+    );
+
+    await expect(fetchDiscovery({ headers: {} })).rejects.toThrow("tag property not found");
+  });
+
+  it("includes fetched_at timestamp", async () => {
+    mockGetSequence(FIXTURES.spaces, FIXTURES.properties, FIXTURES.tags, FIXTURES.types, FIXTURES.stageTags);
+    const before = new Date().toISOString();
+    const result = await fetchDiscovery({ headers: {} });
+    const after = new Date().toISOString();
+    expect(result.fetched_at >= before).toBe(true);
+    expect(result.fetched_at <= after).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// makeDiscoverSpacesHandler
+// ---------------------------------------------------------------------------
+
+const MOCK_RESULT: DiscoveryResult = {
+  spaces: { Career: { id: "sid", tags: { react: "tid" }, types: {} } },
+  fetched_at: "2026-01-01T00:00:00.000Z",
+};
+
+describe("makeDiscoverSpacesHandler", () => {
+  beforeEach(() => {
+    setupAxiosMock();
+    mockGet.mockReset();
+  });
+
+  function mockFetch() {
+    mockGetSequence(FIXTURES.spaces, FIXTURES.properties, FIXTURES.tags, FIXTURES.types, FIXTURES.stageTags);
+  }
+
+  it("returns full result when no path given", async () => {
+    mockFetch();
+    const handle = makeDiscoverSpacesHandler({ headers: {} });
+    const res = await handle({});
+    const data = JSON.parse(res.content[0].text);
+    expect(data.spaces["Career"]).toBeDefined();
+    expect(data.fetched_at).toBeDefined();
+  });
+
+  it("returns sub-tree when path given", async () => {
+    mockFetch();
+    const handle = makeDiscoverSpacesHandler({ headers: {} });
+    const res = await handle({ path: 'spaces["Career"].tags' });
+    const data = JSON.parse(res.content[0].text);
+    expect(data).toEqual({ react: "tag-react", "mcp-modified": "tag-mcp" });
+  });
+
+  it("returns error object for invalid path", async () => {
+    mockFetch();
+    const handle = makeDiscoverSpacesHandler({ headers: {} });
+    const res = await handle({ path: 'spaces["NonExistent"]' });
+    const data = JSON.parse(res.content[0].text);
+    expect(data.error).toMatch(/Path not found/);
+  });
+
+  it("caches result — fetches only once across two calls", async () => {
+    mockFetch();
+    const handle = makeDiscoverSpacesHandler({ headers: {} });
+    await handle({});
+    await handle({});
+    // /v1/spaces is the first GET — should be called exactly once
+    expect(mockGet).toHaveBeenCalledTimes(5); // spaces + props + tags + types + stageTags
+  });
+
+  it("re-fetches when force_refresh=true", async () => {
+    mockFetch();
+    mockFetch(); // second fetch
+    const handle = makeDiscoverSpacesHandler({ headers: {} });
+    await handle({});
+    await handle({ force_refresh: true });
+    expect(mockGet).toHaveBeenCalledTimes(10);
+  });
+
+  it("respects ttlMs from toolConfig", async () => {
+    vi.useFakeTimers();
+    mockFetch();
+    mockFetch();
+    const handle = makeDiscoverSpacesHandler({ headers: {} }, { ttlMs: 100 });
+    await handle({});
+    vi.advanceTimersByTime(101);
+    await handle({});
+    expect(mockGet).toHaveBeenCalledTimes(10);
+    vi.useRealTimers();
+  });
+});
diff --git a/src/mcp/tools/discovery.schema.ts b/src/mcp/tools/discovery.schema.ts
new file mode 100644
index 0000000..ec20cb0
--- /dev/null
+++ b/src/mcp/tools/discovery.schema.ts
@@ -0,0 +1,29 @@
+import { z } from "zod";
+
+const SpaceFilterConfigSchema = z.object({
+  types: z.record(z.string(), z.object({})).optional(),
+});
+
+const DISCOVERY_CONFIG_KNOWN_KEYS = new Set(["ttlMs", "spaces"]);
+const DISCOVERY_CONFIG_EXPECTED_SHAPE = `{ "spaces": { "<SpaceName>": { "types": { "<TypeName>": {} } } }, "ttlMs": <ms> }`;
+
+export const DiscoveryToolConfigSchema = z
+  .object({
+    ttlMs: z.number().int().positive().optional(),
+    spaces: z.record(z.string(), SpaceFilterConfigSchema).optional(),
+  })
+  .loose()
+  .superRefine((val, ctx) => {
+    const unknown = Object.keys(val).filter((k) => !DISCOVERY_CONFIG_KNOWN_KEYS.has(k));
+    if (unknown.length) {
+      ctx.addIssue({
+        code: "custom",
+        message:
+          `DISCOVERY_TOOL_CONFIG: unrecognized key(s) ${unknown.map((k) => `"${k}"`).join(", ")}. ` +
+          `Expected shape: ${DISCOVERY_CONFIG_EXPECTED_SHAPE}`,
+      });
+    }
+  })
+  .transform(({ ttlMs, spaces }) => ({ ttlMs, spaces })); // strip unknown keys after validation
+
+export type DiscoveryToolConfigInput = z.input<typeof DiscoveryToolConfigSchema>;
diff --git a/src/mcp/tools/discovery.ts b/src/mcp/tools/discovery.ts
new file mode 100644
index 0000000..eeac356
--- /dev/null
+++ b/src/mcp/tools/discovery.ts
@@ -0,0 +1,297 @@
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { type AxiosInstance } from "axios";
+import type { HttpClientConfig } from "../../utils/config";
+import { getPlainAxios } from "../../utils/getPlainAxios";
+
+// ---------------------------------------------------------------------------
+// Config (Zod schema lives in discovery.schema.ts)
+// ---------------------------------------------------------------------------
+
+export interface SpaceFilterConfig {
+  /** If omitted, all types in the space are included. */
+  types?: Record<string, Record<string, never>>;
+}
+
+export interface DiscoveryToolConfig {
+  /** Cache TTL in milliseconds. Default: 5 minutes. */
+  ttlMs?: number;
+  /**
+   * Per-space opt-in filter. If omitted, all spaces and types are included.
+   *
+   * @example
+   * { Career: { types: { JobApplication: {} } }, Attic: {} }
+   */
+  spaces?: Record<string, SpaceFilterConfig>;
+}
+
+const SKIPPED_PROPERTY_KEYS = new Set(["tag", "backlinks", "added_date", "created_date", "creator", "links"]);
+
+// ---------------------------------------------------------------------------
+// Output shape
+// ---------------------------------------------------------------------------
+
+export interface SelectOptions {
+  [optionName: string]: string; // name → tag object ID
+}
+
+export interface PropertyMeta {
+  id: string;
+  key: string;
+  format: string;
+  /** Populated for format === "select" | "multi_select" */
+  select?: SelectOptions;
+}
+
+export interface TypeMeta {
+  id: string;
+  key: string;
+  properties: Record<string, PropertyMeta>; // display name → meta
+}
+
+export interface SpaceMeta {
+  id: string;
+  description?: string;
+  /** Space-scoped tags: display name → tag object ID */
+  tags: Record<string, string>;
+  types: Record<string, TypeMeta>; // display name → meta
+}
+
+export interface DiscoveryResult {
+  spaces: Record<string, SpaceMeta>;
+  fetched_at: string;
+}
+
+// ---------------------------------------------------------------------------
+// Path resolution  (bracket notation: spaces["Career"].tags)
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolves a bracket-notation path against an object tree.
+ *
+ * Supported syntax:
+ *   spaces["Career"].tags
+ *   spaces["Attic"].types["Page"].properties
+ *   spaces["Career"].types["JobApplication"].properties["Stage"].select
+ *
+ * Returns the matched sub-tree, or undefined if the path doesn't exist.
+ */
+export function resolvePath(data: unknown, path: string): unknown {
+  const TOKEN_RE = /\["([^"]+)"\]|([^.[]+)/g;
+  const tokens: string[] = [];
+  for (const m of path.matchAll(TOKEN_RE)) {
+    tokens.push(m[1] ?? m[2]!);
+  }
+  let current: unknown = data;
+  for (const token of tokens) {
+    if (current === null || typeof current !== "object") return undefined;
+    current = (current as Record<string, unknown>)[token];
+  }
+  return current;
+}
+
+// ---------------------------------------------------------------------------
+// Fetcher
+// ---------------------------------------------------------------------------
+
+async function get<T>(ax: AxiosInstance, path: string): Promise<T> {
+  const res = await ax.get<{ data: T }>(path);
+  return res.data.data;
+}
+
+async function fetchTags(ax: AxiosInstance, spaceId: string, propertyId: string): Promise<SelectOptions> {
+  const items = await get<Array<{ id: string; name: string }>>(
+    ax,
+    `/v1/spaces/${spaceId}/properties/${propertyId}/tags`,
+  );
+  return Object.fromEntries(items.map((t) => [t.name, t.id]));
+}
+
+async function fetchSpaceMeta(
+  ax: AxiosInstance,
+  spaceId: string,
+  filter: SpaceFilterConfig | undefined,
+): Promise<Pick<SpaceMeta, "tags" | "types">> {
+  const properties = await get<Array<{ id: string; key: string; format: string }>>(
+    ax,
+    `/v1/spaces/${spaceId}/properties`,
+  );
+
+  const tagProp = properties.find((p) => p.key === "tag");
+  if (!tagProp) throw new Error(`Space ${spaceId}: tag property not found`);
+
+  const tags = await fetchTags(ax, spaceId, tagProp.id);
+
+  const allTypes = await get<
+    Array<{
+      id: string;
+      key: string;
+      name: string;
+      properties: Array<{ id: string; key: string; name: string; format: string }>;
+    }>
+  >(ax, `/v1/spaces/${spaceId}/types`);
+
+  const includedTypeNames = filter?.types ? new Set(Object.keys(filter.types)) : null;
+  const relevantTypes = includedTypeNames ? allTypes.filter((t) => includedTypeNames.has(t.name)) : allTypes;
+
+  const types: Record<string, TypeMeta> = {};
+
+  await Promise.all(
+    relevantTypes.map(async (t) => {
+      const properties: Record<string, PropertyMeta> = {};
+
+      await Promise.all(
+        t.properties
+          .filter((p) => !SKIPPED_PROPERTY_KEYS.has(p.key))
+          .map(async (p) => {
+            const meta: PropertyMeta = { id: p.id, key: p.key, format: p.format };
+            if (p.format === "select" || p.format === "multi_select") {
+              meta.select = await fetchTags(ax, spaceId, p.id);
+            }
+            properties[p.name] = meta;
+          }),
+      );
+
+      types[t.name] = { id: t.id, key: t.key, properties };
+    }),
+  );
+
+  return { tags, types };
+}
+
+export async function fetchDiscovery(
+  config: HttpClientConfig,
+  filter?: DiscoveryToolConfig["spaces"],
+): Promise<DiscoveryResult> {
+  const ax = getPlainAxios(config);
+
+  const spaces = await get<Array<{ id: string; name: string; description?: string }>>(ax, "/v1/spaces");
+
+  const includedSpaceNames = filter ? new Set(Object.keys(filter)) : null;
+  const relevantSpaces = includedSpaceNames ? spaces.filter((s) => includedSpaceNames.has(s.name)) : spaces;
+
+  const result: DiscoveryResult = { spaces: {}, fetched_at: new Date().toISOString() };
+
+  await Promise.all(
+    relevantSpaces.map(async (s) => {
+      const spaceFilter = filter?.[s.name];
+      const { tags, types } = await fetchSpaceMeta(ax, s.id, spaceFilter);
+      result.spaces[s.name] = {
+        id: s.id,
+        ...(s.description ? { description: s.description } : {}),
+        tags,
+        types,
+      };
+    }),
+  );
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Tool definition + handler factory
+// ---------------------------------------------------------------------------
+
+export const DISCOVER_SPACES_TOOL_NAME = "discover-spaces";
+
+export const discoverSpacesTool: Tool = {
+  name: DISCOVER_SPACES_TOOL_NAME,
+  description: [
+    "Returns a JSON description of all Anytype spaces: space IDs, types, properties, tags, and select option IDs.",
+    "Call this tool FIRST in any session to resolve IDs before calling create/update/search tools.",
+    'Optional bracket-notation path returns only a sub-tree: spaces["Career"].tags',
+    "Set force_refresh=true only after a schema-mutating operation (creating/modifying a type, tag, or space).",
+  ].join("\n"),
+  inputSchema: {
+    type: "object",
+    properties: {
+      path: {
+        type: "string",
+        description:
+          'Bracket-notation path into the result, e.g. spaces["Career"].tags or spaces["Attic"].types["Page"]. Omit for full structure.',
+      },
+      force_refresh: {
+        type: "boolean",
+        description: "Bypass cache and re-fetch. Use only after schema-mutating operations, not speculatively.",
+        default: false,
+      },
+    },
+  },
+  annotations: {
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+    readOnlyHint: true,
+    title: DISCOVER_SPACES_TOOL_NAME,
+  },
+};
+
+export interface DiscoverSpacesParams {
+  path?: string;
+  force_refresh?: boolean;
+}
+
+/**
+ * Creates the tool handler closed over its own cache instance.
+ * The cache is not exposed — callers interact only via force_refresh.
+ */
+export function makeDiscoverSpacesHandler(
+  config: HttpClientConfig,
+  toolConfig?: DiscoveryToolConfig,
+): (params: DiscoverSpacesParams) => Promise<{ content: Array<{ type: "text"; text: string }> }> {
+  const cache = new DiscoveryCache(toolConfig?.ttlMs);
+  const spaceFilter = toolConfig?.spaces;
+
+  return async ({ path, force_refresh = false }) => {
+    if (force_refresh) cache.invalidate();
+
+    let data = cache.get();
+    if (!data) {
+      data = await fetchDiscovery(config, spaceFilter);
+      cache.set(data);
+    }
+
+    const result = path !== undefined ? resolvePath(data, path) : data;
+
+    if (result === undefined) {
+      return {
+        content: [{ type: "text", text: JSON.stringify({ error: `Path not found: ${path}` }) }],
+      };
+    }
+
+    return { content: [{ type: "text", text: JSON.stringify(result) }] };
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Cache — implementation detail, not exported from the module index
+// ---------------------------------------------------------------------------
+
+interface CacheEntry {
+  data: DiscoveryResult;
+  fetchedAt: number;
+}
+
+class DiscoveryCache {
+  private entry: CacheEntry | undefined;
+  private readonly ttlMs: number;
+
+  constructor(ttlMs = 5 * 60 * 1000) {
+    this.ttlMs = ttlMs;
+  }
+
+  isStale(): boolean {
+    return !this.entry || Date.now() - this.entry.fetchedAt > this.ttlMs;
+  }
+
+  get(): DiscoveryResult | undefined {
+    return this.isStale() ? undefined : this.entry!.data;
+  }
+
+  set(data: DiscoveryResult): void {
+    this.entry = { data, fetchedAt: Date.now() };
+  }
+
+  invalidate(): void {
+    this.entry = undefined;
+  }
+}
diff --git a/src/openapi/parser.ts b/src/openapi/parser.ts
index ec0674d..7d7bf64 100644
--- a/src/openapi/parser.ts
+++ b/src/openapi/parser.ts
@@ -345,6 +345,7 @@ export class OpenAPIToMCPConverter {
         if (mcpMethod) {
           // convert name to kebab-case to conform mcp tool naming convention
           const uniqueName = this.ensureUniqueName(mcpMethod.name).replaceAll("_", "-");
+
           mcpMethod.name = uniqueName;
           methods[apiName]!.push(mcpMethod);
           const toolName = this.options.skipToolNamePrefix ? uniqueName : `${apiName}-${uniqueName}`;
diff --git a/src/utils/__tests__/anytype-launcher.test.ts b/src/utils/__tests__/anytype-launcher.test.ts
new file mode 100644
index 0000000..0eb0df5
--- /dev/null
+++ b/src/utils/__tests__/anytype-launcher.test.ts
@@ -0,0 +1,205 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// ---------------------------------------------------------------------------
+// isLocalBaseUrl — pure function, no mocking needed
+// ---------------------------------------------------------------------------
+describe("isLocalBaseUrl", () => {
+  // Re-import each time to be safe, though it's a pure function
+  async function load() {
+    return (await import("../anytype-launcher")).isLocalBaseUrl;
+  }
+
+  it.each([
+    ["http://127.0.0.1:31009", true],
+    ["http://127.0.0.1:31009/some/path", true],
+    ["http://localhost:3000", true],
+    ["http://localhost", true],
+    ["http://192.168.1.1:31009", false],
+    ["https://api.example.com", false],
+    ["https://anytype.io", false],
+    ["not-a-url", false],
+    ["", false],
+  ])("%s → %s", async (url, expected) => {
+    const isLocal = await load();
+    expect(isLocal(url)).toBe(expected);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// launchAnytypeApp
+// ---------------------------------------------------------------------------
+describe("launchAnytypeApp", () => {
+  const originalPlatform = process.platform;
+
+  afterEach(() => {
+    vi.resetModules();
+    vi.restoreAllMocks();
+    Object.defineProperty(process, "platform", { value: originalPlatform, configurable: true });
+  });
+
+  it("calls `open -a /Applications/Anytype.app` on macOS", async () => {
+    Object.defineProperty(process, "platform", { value: "darwin", configurable: true });
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    vi.resetModules();
+
+    const mockExecFile = vi.fn((_cmd: string, _args: string[], cb: (...a: any[]) => void) => cb(null, "", ""));
+    vi.doMock("node:child_process", () => ({ execFile: mockExecFile }));
+
+    const { launchAnytypeApp } = await import("../anytype-launcher");
+    await launchAnytypeApp();
+
+    expect(mockExecFile).toHaveBeenCalledWith("open", ["-a", "/Applications/Anytype.app"], expect.any(Function));
+  });
+
+  it("is a no-op on non-macOS", async () => {
+    Object.defineProperty(process, "platform", { value: "linux", configurable: true });
+    vi.resetModules();
+
+    const mockExecFile = vi.fn();
+    vi.doMock("node:child_process", () => ({ execFile: mockExecFile }));
+
+    const { launchAnytypeApp } = await import("../anytype-launcher");
+    await launchAnytypeApp();
+
+    expect(mockExecFile).not.toHaveBeenCalled();
+  });
+
+  it("logs error but does not throw when `open` fails", async () => {
+    Object.defineProperty(process, "platform", { value: "darwin", configurable: true });
+    const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    vi.resetModules();
+
+    vi.doMock("node:child_process", () => ({
+      execFile: vi.fn((_cmd: string, _args: string[], cb: (...a: any[]) => void) =>
+        cb(new Error("open: Application not found"), "", ""),
+      ),
+    }));
+
+    const { launchAnytypeApp } = await import("../anytype-launcher");
+    await expect(launchAnytypeApp()).resolves.toBeUndefined();
+    // console.error is called with a single interpolated string
+    expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining("[launcher] Failed to open Anytype app:"));
+  });
+});
+
+// ---------------------------------------------------------------------------
+// waitForUrl
+// ---------------------------------------------------------------------------
+describe("waitForUrl", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.resetModules();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it("returns true immediately when the URL responds on the first poll", async () => {
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue({ status: 200 }));
+
+    const { waitForUrl } = await import("../anytype-launcher");
+    const result = await waitForUrl("http://127.0.0.1:31009/docs/openapi.json", 5_000);
+    expect(result).toBe(true);
+  });
+
+  it("retries and returns true once reachable", async () => {
+    let calls = 0;
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockImplementation(() => {
+        calls++;
+        if (calls < 3) return Promise.reject(new Error("ECONNREFUSED"));
+        return Promise.resolve({ status: 200 });
+      }),
+    );
+
+    const { waitForUrl } = await import("../anytype-launcher");
+    const promise = waitForUrl("http://127.0.0.1:31009/docs/openapi.json", 10_000);
+    // Advance past 2 poll intervals (500 ms each) + some margin
+    await vi.advanceTimersByTimeAsync(1_200);
+    const result = await promise;
+
+    expect(result).toBe(true);
+    expect(calls).toBe(3);
+  });
+
+  it("returns false when timeout expires before URL is reachable", async () => {
+    vi.stubGlobal("fetch", vi.fn().mockRejectedValue(new Error("ECONNREFUSED")));
+
+    const { waitForUrl } = await import("../anytype-launcher");
+    const promise = waitForUrl("http://127.0.0.1:31009/docs/openapi.json", 1_000);
+    await vi.advanceTimersByTimeAsync(2_000);
+    const result = await promise;
+
+    expect(result).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// ensureAnytypeRunning
+// ---------------------------------------------------------------------------
+describe("ensureAnytypeRunning", () => {
+  const originalPlatform = process.platform;
+
+  beforeEach(() => {
+    vi.resetModules();
+    vi.spyOn(console, "error").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    Object.defineProperty(process, "platform", { value: originalPlatform, configurable: true });
+  });
+
+  it("returns false immediately for a non-local base URL", async () => {
+    Object.defineProperty(process, "platform", { value: "darwin", configurable: true });
+    const { ensureAnytypeRunning } = await import("../anytype-launcher");
+    expect(await ensureAnytypeRunning("https://api.example.com")).toBe(false);
+  });
+
+  it("returns false on non-macOS even for a localhost URL", async () => {
+    Object.defineProperty(process, "platform", { value: "linux", configurable: true });
+    const { ensureAnytypeRunning } = await import("../anytype-launcher");
+    expect(await ensureAnytypeRunning("http://127.0.0.1:31009")).toBe(false);
+  });
+
+  it("launches app, polls the spec URL, and returns true when reachable on macOS", async () => {
+    Object.defineProperty(process, "platform", { value: "darwin", configurable: true });
+
+    // Stub child_process so open succeeds
+    vi.doMock("node:child_process", () => ({
+      execFile: vi.fn((_: string, __: string[], cb: (...a: any[]) => void) => cb(null, "", "")),
+    }));
+    // Stub fetch to succeed immediately
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue({ status: 200 }));
+
+    const { ensureAnytypeRunning } = await import("../anytype-launcher");
+    const result = await ensureAnytypeRunning("http://127.0.0.1:31009");
+
+    expect(result).toBe(true);
+    expect(fetch).toHaveBeenCalledWith(
+      "http://127.0.0.1:31009/docs/openapi.json",
+      expect.objectContaining({ signal: expect.any(AbortSignal) }),
+    );
+  });
+
+  it("launches app but returns false when API stays unreachable", async () => {
+    Object.defineProperty(process, "platform", { value: "darwin", configurable: true });
+    vi.useFakeTimers();
+
+    vi.doMock("node:child_process", () => ({
+      execFile: vi.fn((_: string, __: string[], cb: (...a: any[]) => void) => cb(null, "", "")),
+    }));
+    vi.stubGlobal("fetch", vi.fn().mockRejectedValue(new Error("ECONNREFUSED")));
+
+    const { ensureAnytypeRunning } = await import("../anytype-launcher");
+    const promise = ensureAnytypeRunning("http://127.0.0.1:31009");
+    await vi.advanceTimersByTimeAsync(20_000);
+    const result = await promise;
+
+    expect(result).toBe(false);
+    vi.useRealTimers();
+  });
+});
diff --git a/src/utils/__tests__/proxy-config.test.ts b/src/utils/__tests__/config.test.ts
similarity index 59%
rename from src/utils/__tests__/proxy-config.test.ts
rename to src/utils/__tests__/config.test.ts
index 19dd60f..6c3f0fc 100644
--- a/src/utils/__tests__/proxy-config.test.ts
+++ b/src/utils/__tests__/config.test.ts
@@ -1,7 +1,10 @@
+import { rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { Config, ConfigEnv, ENV_KEYS } from "../config.js";
 
-describe("proxy-config utilities", () => {
+describe("config utilities", () => {
   const originalEnv = process.env;
 
   beforeEach(() => {
@@ -185,7 +188,7 @@ describe("proxy-config utilities", () => {
         ANYTYPE_API_BASE_URL: "http://127.0.0.1:31009",
         OPENAPI_MCP_HEADERS: JSON.stringify({ Authorization: "Bearer x" }),
       });
-      expect(config).toEqual<Config>({
+      expect(config).toMatchObject<Config>({
         transport: {
           type: "http",
           host: "0.0.0.0",
@@ -196,4 +199,149 @@ describe("proxy-config utilities", () => {
       });
     });
   });
+
+  describe("config — DISCOVERY_TOOL_CONFIG", () => {
+    const originalEnv = process.env;
+
+    beforeEach(() => {
+      process.env = { ...originalEnv };
+    });
+
+    afterEach(() => {
+      process.env = originalEnv;
+    });
+
+    async function loadConfig(env: Partial<Record<(typeof ENV_KEYS)[number], string>> = {}) {
+      vi.resetModules();
+      ENV_KEYS.forEach((k) => delete process.env[k]);
+      Object.entries(env).forEach(([k, v]) => {
+        if (v === undefined) delete process.env[k];
+        else process.env[k] = v as string;
+      });
+      const { getConfig } = await import("../config.js");
+      return getConfig();
+    }
+
+    it("tools is undefined when DISCOVERY_TOOL_CONFIG is not set", async () => {
+      const config = await loadConfig();
+      expect(config.tools).toBeUndefined();
+    });
+
+    it("parses minimal valid config", async () => {
+      const config = await loadConfig({
+        DISCOVERY_TOOL_CONFIG: JSON.stringify({ ttlMs: 60000 }),
+      });
+      expect(config.tools?.discoverSpaces?.ttlMs).toBe(60000);
+    });
+
+    it("parses spaces filter", async () => {
+      const config = await loadConfig({
+        DISCOVERY_TOOL_CONFIG: JSON.stringify({
+          spaces: { Career: { types: { JobApplication: {} } }, Attic: {} },
+        }),
+      });
+      expect(config.tools?.discoverSpaces?.spaces).toEqual({
+        Career: { types: { JobApplication: {} } },
+        Attic: {},
+      });
+    });
+
+    it("throws on malformed JSON", async () => {
+      await expect(loadConfig({ DISCOVERY_TOOL_CONFIG: "{not valid json" })).rejects.toThrow();
+    });
+
+    it("throws on valid JSON that fails schema — negative ttlMs", async () => {
+      await expect(loadConfig({ DISCOVERY_TOOL_CONFIG: JSON.stringify({ ttlMs: -1 }) })).rejects.toThrow();
+    });
+
+    it("throws on valid JSON that fails schema — wrong type", async () => {
+      await expect(loadConfig({ DISCOVERY_TOOL_CONFIG: JSON.stringify({ ttlMs: "five-minutes" }) })).rejects.toThrow();
+    });
+
+    it("throws on valid JSON that fails schema — unrecognized top-level keys (bare spaces map)", async () => {
+      await expect(
+        loadConfig({
+          DISCOVERY_TOOL_CONFIG: JSON.stringify({
+            Attic: { types: { Daily: {} } },
+          }),
+        }),
+      ).rejects.toThrow(/unrecognized_keys|Unrecognized key/i);
+    });
+
+    it("error message references DISCOVERY_TOOL_CONFIG on malformed JSON", async () => {
+      await expect(loadConfig({ DISCOVERY_TOOL_CONFIG: "oops" })).rejects.toThrow(/DISCOVERY_TOOL_CONFIG/);
+    });
+
+    it("resolves {file:} reference", async () => {
+      const tmp = join(tmpdir(), "discovery-config-test.json");
+      writeFileSync(tmp, JSON.stringify({ ttlMs: 9999 }));
+      const config = await loadConfig({ DISCOVERY_TOOL_CONFIG: `{file:${tmp}}` });
+      expect(config.tools?.discoverSpaces?.ttlMs).toBe(9999);
+      rmSync(tmp);
+    });
+
+    it("throws with readable message on missing file reference", async () => {
+      await expect(loadConfig({ DISCOVERY_TOOL_CONFIG: "{file:/nonexistent/path.json}" })).rejects.toThrow(
+        /Failed to read file reference/,
+      );
+    });
+  });
+
+  // ─── JsonString helper (via OPENAPI_MCP_HEADERS — already uses it) ──────────
+
+  describe("config — JsonString helper via OPENAPI_MCP_HEADERS", () => {
+    const originalEnv = process.env;
+
+    beforeEach(() => {
+      process.env = { ...originalEnv };
+    });
+    afterEach(() => {
+      process.env = originalEnv;
+    });
+
+    async function loadConfig(env: Partial<Record<(typeof ENV_KEYS)[number], string>> = {}) {
+      vi.resetModules();
+      ENV_KEYS.forEach((k) => delete process.env[k]);
+      Object.entries(env).forEach(([k, v]) => {
+        if (v === undefined) delete process.env[k];
+        else process.env[k] = v as string;
+      });
+      const { getConfig } = await import("../config.js");
+      return getConfig();
+    }
+
+    it("logs error referencing OPENAPI_MCP_HEADERS on invalid JSON", async () => {
+      const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+      await loadConfig({ OPENAPI_MCP_HEADERS: "{bad" });
+      expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining("OPENAPI_MCP_HEADERS"));
+      consoleSpy.mockRestore();
+    });
+  });
+
+  describe("config — MCP_INSTRUCTIONS", () => {
+    it("instructions is undefined when MCP_INSTRUCTIONS is unset", async () => {
+      const config = await loadConfig();
+      expect(config.instructions).toBeUndefined();
+    });
+
+    it('"false" → false', async () => {
+      const config = await loadConfig({ MCP_INSTRUCTIONS: "false" });
+      expect(config.instructions).toBe(false);
+    });
+
+    it('"true" → undefined (caller uses bundled)', async () => {
+      const config = await loadConfig({ MCP_INSTRUCTIONS: "true" });
+      expect(config.instructions).toBeUndefined();
+    });
+
+    it("custom string → passed through as-is", async () => {
+      const config = await loadConfig({ MCP_INSTRUCTIONS: "Do only what I say." });
+      expect(config.instructions).toBe("Do only what I say.");
+    });
+
+    it('empty string → undefined (treated as "true")', async () => {
+      const config = await loadConfig({ MCP_INSTRUCTIONS: "" });
+      expect(config.instructions).toBeUndefined();
+    });
+  });
 });
diff --git a/src/utils/__tests__/getPlainAxios.test.ts b/src/utils/__tests__/getPlainAxios.test.ts
new file mode 100644
index 0000000..8d916f1
--- /dev/null
+++ b/src/utils/__tests__/getPlainAxios.test.ts
@@ -0,0 +1,29 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { _resetPlainAxios, getPlainAxios } from "../getPlainAxios";
+
+describe("getPlainAxios", () => {
+  beforeEach(() => _resetPlainAxios());
+  afterEach(() => _resetPlainAxios());
+
+  it("returns an axios instance", () => {
+    const ax = getPlainAxios({ headers: {} });
+    expect(ax).toBeDefined();
+    expect(typeof ax.get).toBe("function");
+  });
+
+  it("returns the same instance on repeated calls", () => {
+    const a = getPlainAxios({ headers: {} });
+    const b = getPlainAxios({ headers: {} });
+    expect(a).toBe(b);
+  });
+
+  it("sets baseURL from config", () => {
+    const ax = getPlainAxios({ baseUrl: "http://127.0.0.1:9999", headers: {} });
+    expect((ax.defaults as any).baseURL).toBe("http://127.0.0.1:9999");
+  });
+
+  it("falls back to DEFAULT_BASE_URL when baseUrl is absent", () => {
+    const ax = getPlainAxios({ headers: {} });
+    expect((ax.defaults as any).baseURL).toBe("http://127.0.0.1:31009");
+  });
+});
diff --git a/src/utils/anytype-launcher.ts b/src/utils/anytype-launcher.ts
new file mode 100644
index 0000000..1c6a398
--- /dev/null
+++ b/src/utils/anytype-launcher.ts
@@ -0,0 +1,75 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+const ANYTYPE_APP_PATH = "/Applications/Anytype.app";
+/** How long to wait for Anytype to become reachable after launch (ms). */
+const LAUNCH_TIMEOUT_MS = 15_000;
+/** Poll interval while waiting (ms). */
+const POLL_INTERVAL_MS = 500;
+
+/**
+ * Returns true when the resolved base URL targets localhost / loopback,
+ * making it safe to auto-launch the local Anytype application.
+ */
+export function isLocalBaseUrl(baseUrl: string): boolean {
+  try {
+    const { hostname } = new URL(baseUrl);
+    return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1";
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Attempts to open the Anytype desktop application on macOS.
+ * No-op on non-macOS platforms.
+ * Resolves immediately after dispatching `open`; does NOT wait for readiness.
+ */
+export async function launchAnytypeApp(): Promise<void> {
+  if (process.platform !== "darwin") return;
+  console.error(`[launcher] Starting Anytype app: ${ANYTYPE_APP_PATH}`);
+  try {
+    await execFileAsync("open", ["-a", ANYTYPE_APP_PATH]);
+  } catch (err: any) {
+    console.error(`[launcher] Failed to open Anytype app: ${err.message}`);
+  }
+}
+
+/**
+ * Polls `url` until it responds (any HTTP status) or `timeoutMs` is exceeded.
+ * Returns true if reachable within the timeout.
+ */
+export async function waitForUrl(url: string, timeoutMs = LAUNCH_TIMEOUT_MS): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(url, { signal: AbortSignal.timeout(POLL_INTERVAL_MS) });
+      if (res.status > 0) return true;
+    } catch {
+      // not yet up
+    }
+    await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+  }
+  return false;
+}
+
+/**
+ * If the base URL is local, launches the Anytype app and waits for it to become
+ * reachable. Returns true if the app came up within the timeout, false otherwise.
+ * Safe to call on non-macOS (no-op, returns false).
+ */
+export async function ensureAnytypeRunning(baseUrl: string): Promise<boolean> {
+  if (!isLocalBaseUrl(baseUrl) || process.platform !== "darwin") return false;
+  await launchAnytypeApp();
+  const specUrl = `${baseUrl}/docs/openapi.json`;
+  console.error(`[launcher] Waiting for Anytype API at ${specUrl}…`);
+  const reachable = await waitForUrl(specUrl);
+  if (reachable) {
+    console.error("[launcher] Anytype API is reachable.");
+  } else {
+    console.error(`[launcher] Anytype API did not become reachable within ${LAUNCH_TIMEOUT_MS / 1000}s.`);
+  }
+  return reachable;
+}
diff --git a/src/utils/config.ts b/src/utils/config.ts
index d35da50..1695a02 100644
--- a/src/utils/config.ts
+++ b/src/utils/config.ts
@@ -1,5 +1,7 @@
 import { URL } from "node:url";
 import { z } from "zod";
+import { DiscoveryToolConfigSchema } from "../mcp/tools/discovery.schema";
+import { resolveFileRef } from "./resolveFileRef";
 
 export const ENV_KEYS = [
   "MCP_TRANSPORT",
@@ -8,6 +10,8 @@ export const ENV_KEYS = [
   "MCP_PASSTHROUGH_HEADERS",
   "ANYTYPE_API_BASE_URL",
   "OPENAPI_MCP_HEADERS",
+  "DISCOVERY_TOOL_CONFIG",
+  "MCP_INSTRUCTIONS",
 ] as const;
 
 export type ConfigEnv = Partial<Record<(typeof ENV_KEYS)[number], string>>;
@@ -18,6 +22,26 @@ export type ConfigEnv = Partial<Record<(typeof ENV_KEYS)[number], string>>;
  */
 export const DEFAULT_PASSTHROUGH_HEADERS = ["authorization", "anytype-version"] as const;
 
+/**
+ * Parses a JSON string and validates it against the given schema.
+ * Produces a Zod error on malformed JSON rather than throwing.
+ */
+const JsonString = <T extends z.ZodTypeAny>(schema: T, envKey?: string) =>
+  z
+    .string()
+    .transform((val, ctx) => {
+      try {
+        return JSON.parse(val);
+      } catch {
+        ctx.addIssue({
+          code: "custom",
+          message: `${envKey ? `${envKey}: Invalid JSON` : "Invalid JSON"}: ${val}`,
+        });
+        return z.NEVER;
+      }
+    })
+    .pipe(schema);
+
 const TransportConfigSchema = z.discriminatedUnion("type", [
   z.object({ type: z.literal("stdio") }),
   z.object({
@@ -58,22 +82,52 @@ const HttpClientConfigSchema = z.object({
    * JSON object of headers forwarded to the upstream API on every request.
    * Parsed from OPENAPI_MCP_HEADERS.
    */
-  headers: z
-    .string()
+  headers: JsonString(z.record(z.string(), z.string()), "OPENAPI_MCP_HEADERS")
     .optional()
-    .transform((val) => {
-      if (!val) return {} as Record<string, string>;
-      try {
-        return z.record(z.string(), z.string()).parse(JSON.parse(val));
-      } catch {
-        console.error("Failed to parse OPENAPI_MCP_HEADERS, ignoring");
-        return {} as Record<string, string>;
-      }
-    }),
+    .catch((ctx) => {
+      console.error(ctx.issues.map(({ message }) => message).join("; "));
+      return undefined;
+    })
+    .default({}),
 });
 
 export type HttpClientConfig = z.infer<typeof HttpClientConfigSchema>;
 
+const ToolsConfigSchema = z
+  .object({
+    /**
+     * Configuration for the discover-spaces tool.
+     * Parsed from DISCOVERY_TOOL_CONFIG (JSON string).
+     */
+    discoverSpaces: JsonString(DiscoveryToolConfigSchema, "DISCOVERY_TOOL_CONFIG").optional(),
+  })
+  .transform((val) => {
+    // All fields undefined → return undefined so config.tools is absent
+    if (Object.values(val).every((v) => v === undefined)) return undefined;
+    return val;
+  });
+
+export type ToolsConfig = z.infer<typeof ToolsConfigSchema>;
+
+/**
+ * Instructions config.
+ *
+ * Env: MCP_INSTRUCTIONS
+ *   unset / "true"  → bundled instructions.md content (injected at build time)
+ *   "false"         → disabled; no instructions emitted
+ *   any other string → used as literal instructions content
+ *
+ * Resolved value: string (content) | false (disabled) | undefined (use bundled default)
+ */
+const InstructionsSchema = z
+  .string()
+  .transform((v): string | false | undefined => {
+    if (v === "false") return false;
+    if (v === "true" || v === "") return undefined; // undefined → caller uses bundled
+    return v;
+  })
+  .optional();
+
 /**
  * Anytype MCP server config schema.
  */
@@ -88,6 +142,17 @@ const ConfigSchema = z.object({
    * Target/upstream Anytype OpenAPI client config.
    */
   httpClient: HttpClientConfigSchema,
+
+  /**
+   * Hand-crafted tool configurations.
+   */
+  tools: ToolsConfigSchema.optional(),
+
+  /**
+   * Instructions broadcast to MCP clients on connect.
+   * undefined = use bundled instructions.md; false = disabled; string = custom content.
+   */
+  instructions: InstructionsSchema,
 });
 
 export type Config = z.infer<typeof ConfigSchema>;
@@ -108,8 +173,10 @@ export function getConfig() {
           : { type: "stdio" },
       httpClient: {
         baseUrl: process.env.ANYTYPE_API_BASE_URL,
-        headers: process.env.OPENAPI_MCP_HEADERS,
+        headers: resolveFileRef(process.env.OPENAPI_MCP_HEADERS),
       },
+      tools: { discoverSpaces: resolveFileRef(process.env.DISCOVERY_TOOL_CONFIG) },
+      instructions: resolveFileRef(process.env.MCP_INSTRUCTIONS),
     });
   }
 
diff --git a/src/utils/getPlainAxios.ts b/src/utils/getPlainAxios.ts
new file mode 100644
index 0000000..e238374
--- /dev/null
+++ b/src/utils/getPlainAxios.ts
@@ -0,0 +1,35 @@
+// ---------------------------------------------------------------------------
+// Plain Axios singleton
+// NOTE: header injection via interceptors is deferred to the next PR that
+// refactors HttpClient.withHeaders() to the same pattern.
+// ---------------------------------------------------------------------------
+
+import axios, { type AxiosInstance } from "axios";
+import { DEFAULT_BASE_URL } from "./base-url";
+import { HttpClientConfig } from "./config";
+
+let _axiosInstance: AxiosInstance | undefined;
+
+/**
+ * Returns a plain (non-OpenAPI-aware) Axios instance initialised from the
+ * same HttpClientConfig as the main HttpClient. Singleton per process.
+ */
+export function getPlainAxios(config: HttpClientConfig): AxiosInstance {
+  if (!_axiosInstance) {
+    _axiosInstance = axios.create({
+      baseURL: config.baseUrl ?? DEFAULT_BASE_URL,
+      headers: {
+        Accept: "application/json",
+        "Content-Type": "application/json",
+        "User-Agent": "anytype-mcp-server",
+        ...config.headers,
+      },
+    });
+  }
+  return _axiosInstance;
+}
+
+/** Exposed for tests only. */
+export function _resetPlainAxios(): void {
+  _axiosInstance = undefined;
+}
diff --git a/src/utils/resolveFileRef.ts b/src/utils/resolveFileRef.ts
new file mode 100644
index 0000000..313037e
--- /dev/null
+++ b/src/utils/resolveFileRef.ts
@@ -0,0 +1,18 @@
+import { readFileSync } from "node:fs";
+
+/**
+ * Resolves a "{file:/path/to/file}" reference to its file contents,
+ * or returns the value unchanged if it is not a file reference.
+ */
+export function resolveFileRef(value: string | undefined): string | undefined {
+  if (!value?.startsWith("{file:")) return value;
+  if (!value.endsWith("}")) throw new Error(`Closing brace is missing in the file reference: "${value}"`);
+
+  let path = value.slice(6, -1).trim(); // strip "{file:" prefix and "}" suffix
+  if (path.startsWith("~")) path = `${process.env.HOME}${path.slice(1)}`;
+  try {
+    return readFileSync(path, "utf8");
+  } catch (err) {
+    throw new Error(`Failed to read file reference "${value}": ${(err as NodeJS.ErrnoException).message}`);
+  }
+}
diff --git a/src/utils/resolveInstructions.ts b/src/utils/resolveInstructions.ts
new file mode 100644
index 0000000..6ef1ed0
--- /dev/null
+++ b/src/utils/resolveInstructions.ts
@@ -0,0 +1,23 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Resolved at import time: bundled string in CLI, file read in dev/ts-node.
+ */
+export function resolveInstructions(configured: string | false | undefined): string | undefined {
+  if (configured === false) return undefined;
+  if (typeof configured === "string") return configured;
+  // undefined → use bundled (injected by esbuild) or fall back to reading the file
+  try {
+    return __BUNDLED_INSTRUCTIONS__;
+  } catch {
+    // dev mode: not bundled, read from source tree
+    try {
+      const __dirname = dirname(fileURLToPath(import.meta.url));
+      return readFileSync(join(__dirname, "../../instructions.md"), "utf8");
+    } catch {
+      return undefined;
+    }
+  }
+}