noticedso · simaonogueira101 · May 11, 2026 · May 11, 2026 · May 11, 2026
diff --git a/README.md b/README.md
@@ -21,17 +21,44 @@ The MCP server exposes two meta-tools — **`search`** and **`execute`** — bac
 
 > Upgrading from 0.2.x? The tool surface changed: clients that called `search_network` / `get_connection_path` directly should now call `search` (to discover the capability) followed by `execute { capability: "search_network", args: { query: "…" } }`. MCP-aware LLMs handle this discovery automatically.
 
-Pick your client below.
+You have two ways to connect: **hosted** (no install, Streamable HTTP) or **stdio** (this package via `npx`). The hosted server runs your queries against `noticed.so` so anyone with a noticed account can use it. The stdio server is useful when your MCP client can't speak HTTP, or when you're running a self-hosted noticed instance.
 
-### Claude Code
+### Hosted MCP server (recommended — no install)
+
+Point any MCP client that supports Streamable HTTP at `https://mcp.noticed.so/api/mcp` with your noticed API key as a Bearer header. Mint a key at [noticed.so/dashboard/api-keys](https://noticed.so/dashboard/api-keys).
+
+**Claude Code** (one command):
+
+```bash
+claude mcp add --transport http --scope user noticed https://mcp.noticed.so/api/mcp --header "Authorization: Bearer nk_live_…"
+```
+
+**Cursor, Claude Desktop, Zed, VS Code Copilot, Windsurf, Cline** — all support URL + header config. Drop the `command/args/env` block from any of the stdio snippets below and replace with:
+
+```json
+{
+  "mcpServers": {
+    "noticed": {
+      "url": "https://mcp.noticed.so/api/mcp",
+      "headers": { "Authorization": "Bearer nk_live_…" }
+    }
+  }
+}
+```
+
+### Stdio MCP server (this package)
+
+Pick your client below for the stdio install.
+
+#### Claude Code
 
 ```bash
 claude mcp add --scope project noticed -- npx -y @noticed/cli mcp
 ```
 
 `--scope project` writes to `.mcp.json` at your repo root so the server is shared with everyone on the team. Drop the flag for a personal-scope install.
 
-### Claude Desktop
+#### Claude Desktop
 
 Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
 
@@ -42,15 +69,14 @@ Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) o
       "command": "npx",
       "args": ["-y", "@noticed/cli", "mcp"],
       "env": {
-        "NOTICED_API_URL": "https://your-instance.noticed.so",
         "NOTICED_API_KEY": "nk_live_…"
       }
     }
   }
 }
 ```
 
-### Cursor
+#### Cursor
 
 Edit `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):
 
@@ -60,13 +86,13 @@ Edit `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):
     "noticed": {
       "command": "npx",
       "args": ["-y", "@noticed/cli", "mcp"],
-      "env": { "NOTICED_API_URL": "https://your-instance.noticed.so", "NOTICED_API_KEY": "nk_live_…" }
+      "env": { "NOTICED_API_KEY": "nk_live_…" }
     }
   }
 }
 ```
 
-### VS Code (Copilot Chat, GitHub Copilot agent mode)
+#### VS Code (Copilot Chat, GitHub Copilot agent mode)
 
 Edit `.vscode/mcp.json` for workspace, or run **MCP: Open User Configuration** for global:
 
@@ -77,15 +103,15 @@ Edit `.vscode/mcp.json` for workspace, or run **MCP: Open User Configuration** f
       "type": "stdio",
       "command": "npx",
       "args": ["-y", "@noticed/cli", "mcp"],
-      "env": { "NOTICED_API_URL": "https://your-instance.noticed.so", "NOTICED_API_KEY": "nk_live_…" }
+      "env": { "NOTICED_API_KEY": "nk_live_…" }
     }
   }
 }
 ```
 
 Note VS Code uses `servers` (not `mcpServers`) and requires `type`.
 
-### Windsurf
+#### Windsurf
 
 Edit `~/.codeium/windsurf/mcp_config.json`:
 
@@ -95,13 +121,13 @@ Edit `~/.codeium/windsurf/mcp_config.json`:
     "noticed": {
       "command": "npx",
       "args": ["-y", "@noticed/cli", "mcp"],
-      "env": { "NOTICED_API_URL": "https://your-instance.noticed.so", "NOTICED_API_KEY": "nk_live_…" }
+      "env": { "NOTICED_API_KEY": "nk_live_…" }
     }
   }
 }
 ```
 
-### Cline (VS Code)
+#### Cline (VS Code)
 
 Edit `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`:
 
@@ -111,13 +137,13 @@ Edit `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-d
     "noticed": {
       "command": "npx",
       "args": ["-y", "@noticed/cli", "mcp"],
-      "env": { "NOTICED_API_URL": "https://your-instance.noticed.so", "NOTICED_API_KEY": "nk_live_…" }
+      "env": { "NOTICED_API_KEY": "nk_live_…" }
     }
   }
 }
 ```
 
-### Continue
+#### Continue
 
 MCP works in **agent mode** only. Add `.continue/mcpServers/noticed.yaml`:
 
@@ -127,11 +153,10 @@ mcpServers:
     command: npx
     args: ["-y", "@noticed/cli", "mcp"]
     env:
-      NOTICED_API_URL: https://your-instance.noticed.so
       NOTICED_API_KEY: nk_live_…
 ```
 
-### Zed
+#### Zed
 
 Edit `~/.config/zed/settings.json` (note: key is `context_servers`, not `mcpServers`):
 
@@ -141,7 +166,7 @@ Edit `~/.config/zed/settings.json` (note: key is `context_servers`, not `mcpServ
     "noticed": {
       "command": "npx",
       "args": ["-y", "@noticed/cli", "mcp"],
-      "env": { "NOTICED_API_URL": "https://your-instance.noticed.so", "NOTICED_API_KEY": "nk_live_…" }
+      "env": { "NOTICED_API_KEY": "nk_live_…" }
     }
   }
 }
@@ -175,9 +200,8 @@ git clone https://github.com/noticedso/cli ~/.claude/plugins/noticed
 ## Quick start (CLI)
 
 ```bash
-# 1. Mint an API key in your noticed dashboard at /dashboard/api-keys
+# 1. Mint an API key at https://www.noticed.so/dashboard/api-keys
 # 2. Configure credentials
-noticed config --set-url https://your-instance.noticed.so
 noticed config --set-key nk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 
 # 3. Search your network
@@ -271,8 +295,8 @@ noticed completion fish > ~/.config/fish/completions/noticed.fish
 
 | Variable | Description | Required |
 |----------|-------------|----------|
-| `NOTICED_API_URL` | Base URL of your noticed instance | yes |
-| `NOTICED_API_KEY` | API key for authentication | yes |
+| `NOTICED_API_KEY` | API key minted at https://www.noticed.so/dashboard/api-keys | yes |
+| `NOTICED_API_URL` | Override the noticed instance URL. Defaults to `https://www.noticed.so` — only set this if you self-host | no |
 | `NOTICED_BASE_URL` | Alias for `NOTICED_API_URL` | no |
 
 Precedence: CLI flags > environment variables > config file.
@@ -281,18 +305,39 @@ Precedence: CLI flags > environment variables > config file.
 
 ## MCP tools
 
+The MCP server exposes exactly two tools — both meta-tools that bridge to the noticed agent's capability registry. The client's LLM uses `search` to discover capabilities at runtime, then calls `execute` by name.
+
 | Tool | Description |
 |------|-------------|
-| `search_network` | Search developers by name, company, skill, or topic. Optional `source`, `sort`, `limit`, `offset`, `include_paths`. |
-| `get_connection_path` | Find the shortest path to a target person. Accepts a natural-language `query`, an explicit `github_user_id`, or a `linkedin_username`. |
+| `search` | Discover noticed capabilities by keyword and optional category. Returns names, descriptions, categories, and JSON parameter schemas. Call with no arguments to list everything. |
+| `execute` | Run a capability by exact name. Pass capability arguments in the `args` object. |
+
+Example client-side flow:
+
+```jsonc
+// 1. Find the right capability
+tools/call search { "query": "missions" }
+// → returns [{ name: "list_missions", parameters: {…}, … }, …]
+
+// 2. Run it
+tools/call execute { "capability": "list_missions", "args": {} }
+// → returns the user's missions
+```
+
+The ~50 chat-safe capabilities cover developer-network search (`search_network`, `get_connection_path`, `my_profile`, `my_network`, `my_activity`, …), missions/goals/milestones, PRM (people / interactions / stages), virtual filesystem and persona files, persistent memory, web search and fetch, and cron scheduling. Nine chat-only capabilities (in-chat messaging, referral invites, Cursor Cloud agents) are filtered server-side.
 
 Test with the MCP Inspector:
 
 ```bash
+# stdio
 npx @modelcontextprotocol/inspector npx @noticed/cli mcp
+
+# hosted (Streamable HTTP) — set Authorization: Bearer <key> in the inspector UI
+npx @modelcontextprotocol/inspector
+# URL: https://mcp.noticed.so/api/mcp
 ```
 
-Or by hand:
+Or by hand against the stdio server:
 
 ```bash
 echo '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | noticed mcp
@@ -307,7 +352,7 @@ echo '{"jsonrpc":"2.0","method":"tools/list","id":2}' | noticed mcp
 import { NoticedApiClient } from "@noticed/cli";
 
 const client = new NoticedApiClient({
-  baseUrl: "https://your-instance.noticed.so",
+  baseUrl: "https://www.noticed.so",
   apiKey: "nk_live_…",
 });
 
@@ -331,6 +376,22 @@ npm run check-types
 
 ---
 
+## Self-hosting noticed
+
+The CLI defaults to the hosted noticed instance at `https://www.noticed.so`. Self-hosting noticed itself is possible but operationally heavy — the value depends on a pre-ingested GitHub + LinkedIn collaboration graph (hundreds of GiB of ClickHouse data, daily GHArchive ingestion, paid LinkedIn API access, OpenAI + Anthropic keys, NextAuth OAuth apps). Most users want the hosted service.
+
+If you do run your own instance, set `NOTICED_API_URL` to its URL — everything else works the same:
+
+```bash
+export NOTICED_API_URL=https://noticed.your-domain.com
+export NOTICED_API_KEY=nk_live_…
+noticed search "AI engineers"
+```
+
+The source for the hosted service lives at https://github.com/noticedso/noticed.
+
+---
+
 ## License
 
 [MIT](LICENSE) © noticed
diff --git a/mcp.json b/mcp.json
@@ -4,7 +4,6 @@
       "command": "npx",
       "args": ["-y", "@noticed/cli", "mcp"],
       "env": {
-        "NOTICED_API_URL": "https://your-instance.noticed.so",
         "NOTICED_API_KEY": "your-api-key"
       }
     }

diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@noticed/cli",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "CLI and MCP server for noticed — search your developer network, trace connections, find the shortest path to anyone through GitHub and LinkedIn.",
   "keywords": [
     "noticed",

diff --git a/server.json b/server.json
@@ -2,7 +2,7 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.noticedso/cli",
   "description": "Search your developer network and trace connection paths via GitHub & LinkedIn.",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "repository": {
     "url": "https://github.com/noticedso/cli",
     "source": "github"
@@ -11,7 +11,7 @@
     {
       "registryType": "npm",
       "identifier": "@noticed/cli",
-      "version": "0.3.0",
+      "version": "0.3.1",
       "transport": { "type": "stdio" },
       "runtimeHint": "npx",
       "runtimeArguments": [
@@ -23,8 +23,8 @@
       "environmentVariables": [
         {
           "name": "NOTICED_API_URL",
-          "description": "Base URL of your noticed instance (e.g. https://noticed.so)",
-          "isRequired": true
+          "description": "Base URL of the noticed instance. Defaults to https://www.noticed.so — only set this if you self-host noticed.",
+          "isRequired": false
         },
         {
           "name": "NOTICED_API_KEY",

diff --git a/src/api-client.ts b/src/api-client.ts
@@ -247,20 +247,28 @@ export class NoticedApiClient {
 // Config helpers
 // ---------------------------------------------------------------------------
 
+/**
+ * The canonical hosted noticed instance. Self-hosting noticed is technically
+ * possible but operationally unrealistic — the value depends on a pre-ingested
+ * GHArchive + LinkedIn graph that takes weeks to build. Defaulting to the
+ * hosted service is the right tradeoff for ~100% of users.
+ *
+ * Self-hosters can still override by setting NOTICED_API_URL or
+ * NOTICED_BASE_URL explicitly.
+ */
+const DEFAULT_BASE_URL = "https://www.noticed.so";
+
 export function createClientFromEnv(): NoticedApiClient {
-  const baseUrl = process.env["NOTICED_API_URL"] ?? process.env["NOTICED_BASE_URL"];
+  const baseUrl =
+    process.env["NOTICED_API_URL"] ??
+    process.env["NOTICED_BASE_URL"] ??
+    DEFAULT_BASE_URL;
   const apiKey = process.env["NOTICED_API_KEY"];
 
-  if (!baseUrl) {
-    throw new Error(
-      "Missing NOTICED_API_URL or NOTICED_BASE_URL environment variable.\n" +
-        "Set it to the URL of your noticed instance (e.g. https://noticed.so).",
-    );
-  }
   if (!apiKey) {
     throw new Error(
       "Missing NOTICED_API_KEY environment variable.\n" +
-        "Create an API key in your noticed dashboard.",
+        "Mint an API key at https://www.noticed.so/dashboard/api-keys.",
     );
   }