Cli

@noticed/cli

[npm version] [npm downloads] [CI] [License: MIT]

CLI, stdio compatibility bridge, and Claude Code plugin for noticed — search your network, manage relationships, and use the canonical noticed MCP from HTTP or stdio-only clients.

npm install -g @noticed/clinoticed search "AI engineers"noticed path @sarahml

Add to your AI coding agent

The canonical MCP exposes every reviewed noticed capability as a direct, typed tool: relationship search and dossiers, missions and goals, people and interactions, lists and views, memory, scheduled work, and more. The hosted server owns the tool registry and schemas so every client sees the same current surface.

Upgrading from 0.3.x? Restart with @noticed/[email protected] or newer. The retired search / execute meta-tools are replaced by the canonical direct tools returned by https://mcp.noticed.so/api/mcp.

You have two ways to connect: hosted (no install, Streamable HTTP) or stdio (this package via npx). Both connect to the same server and expose the same direct tools. Use stdio only when your MCP client cannot speak Streamable HTTP.

Hosted MCP server (recommended — no install)

https://mcp.noticed.so/api/mcp is a hosted Streamable HTTP endpoint. Two authentication paths are supported; pick whichever your client prefers.

OAuth (claude.ai web, ChatGPT MCP, anything that does OAuth discovery)

The hosted server is a spec-compliant OAuth 2.1 authorization server with Dynamic Client Registration. Clients that follow the MCP authorization profile — including claude.ai's custom connectors and ChatGPT's MCP integration — discover the server, register themselves, and walk the user through a consent screen automatically. No API key needed in the client config.

claude.ai custom connector: open Settings → Connectors → Add custom connector, paste https://mcp.noticed.so/api/mcp as the URL. claude.ai handles the rest. Connected applications are visible (and revocable) at noticed.so/dashboard/oauth-grants.

API key Bearer (Claude Code, Cursor, anything that supports a custom header)

For clients that can set an Authorization: Bearer … header, mint a key at noticed.so/dashboard/api-keys and use it directly — no OAuth flow needed.

Claude Code (one command):

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:

{  "mcpServers": {    "noticed": {      "url": "https://mcp.noticed.so/api/mcp",      "headers": { "Authorization": "Bearer nk_live_…" }    }  }}

Stdio bridge (this package)

The noticed mcp command securely proxies stdio to the canonical hosted MCP. Pick your client below for the stdio install.

Claude Code

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

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{  "mcpServers": {    "noticed": {      "command": "npx",      "args": ["-y", "@noticed/cli", "mcp"],      "env": {        "NOTICED_API_KEY": "nk_live_…"      }    }  }}

Cursor

Edit ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

{  "mcpServers": {    "noticed": {      "command": "npx",      "args": ["-y", "@noticed/cli", "mcp"],      "env": { "NOTICED_API_KEY": "nk_live_…" }    }  }}

VS Code (Copilot Chat, GitHub Copilot agent mode)

Edit .vscode/mcp.json for workspace, or run MCP: Open User Configuration for global:

{  "servers": {    "noticed": {      "type": "stdio",      "command": "npx",      "args": ["-y", "@noticed/cli", "mcp"],      "env": { "NOTICED_API_KEY": "nk_live_…" }    }  }}

Note VS Code uses servers (not mcpServers) and requires type.

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

{  "mcpServers": {    "noticed": {      "command": "npx",      "args": ["-y", "@noticed/cli", "mcp"],      "env": { "NOTICED_API_KEY": "nk_live_…" }    }  }}

Cline (VS Code)

Edit ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json:

{  "mcpServers": {    "noticed": {      "command": "npx",      "args": ["-y", "@noticed/cli", "mcp"],      "env": { "NOTICED_API_KEY": "nk_live_…" }    }  }}

Continue

MCP works in agent mode only. Add .continue/mcpServers/noticed.yaml:

mcpServers:  - name: noticed    command: npx    args: ["-y", "@noticed/cli", "mcp"]    env:      NOTICED_API_KEY: nk_live_…

Zed

Edit ~/.config/zed/settings.json (note: key is context_servers, not mcpServers):

{  "context_servers": {    "noticed": {      "command": "npx",      "args": ["-y", "@noticed/cli", "mcp"],      "env": { "NOTICED_API_KEY": "nk_live_…" }    }  }}

Agent Skill and plugin

The portable noticed Agent Skill works in Codex, Claude Code, Cursor, and other clients supported by the open skills ecosystem:

# Inspect the skill before installationnpx skills add noticedso/cli --list
# Install globally for Codex and Claude Codenpx skills add noticedso/cli --skill noticed-search -g \  --agent codex --agent claude-code -y

The repository is also an Agent Plugins 1.0 package. It carries a portable plugin.json, skills/, and mcp.json, plus a Claude Code compatibility manifest under .claude-plugin/. The MCP definition starts the version-pinned stdio bridge; configure NOTICED_API_KEY in the client environment or run noticed config --set-key … before querying production data.

To install the Claude Code compatibility plugin directly from source:

git clone https://github.com/noticedso/cli ~/.claude/plugins/noticed# restart Claude Code

Quick start (CLI)

# 1. Mint an API key at https://www.noticed.so/dashboard/api-keys# 2. Configure credentialsnoticed config --set-key nk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# 3. Search your networknoticed search "react developers"
# 4. Find the shortest path to a specific personnoticed path @sarahmlnoticed path --li sarah-chen
# 5. JSON output for scriptingnoticed search "frontend" --json | jq '.hits[].github_login'

Authentication

The CLI authenticates with a Bearer API key. Mint one at /dashboard/api-keys — the secret is shown once at create time, so copy it immediately. Tokens look like nk_live_…, are rate-limited to 60 requests per minute per key, and can be revoked from the same page.

CLI commands

noticed search <query>

Search your developer network for people, companies, skills, or topics.

noticed search "AI engineers"                  # natural languagenoticed search "@sarahml"                      # GitHub usernamenoticed search "CTO at Vercel"                 # job title + companynoticed search "kubernetes" --source github    # filter by sourcenoticed search "react" --limit 10 --json       # paginated JSON outputnoticed search "engineers" --csv > out.csv     # CSV exportnoticed search "Sarah Chen" --paths            # also fetch paths to top hits

noticed path [target]

Find the shortest connection path between you and a person.

noticed path @sarahml             # by GitHub loginnoticed path 12345                # by github_user_idnoticed path --li sarah-chen      # by LinkedIn usernamenoticed path @sarahml --json      # machine-readable

Logins are resolved via search before the path lookup. Pass --li to skip the search step and look up by LinkedIn username directly.

noticed config

noticed config                     # show current confignoticed config --set-url <url>     # set API URLnoticed config --set-key <key>     # set API keynoticed config --show              # show current config

Config is stored at ~/.config/noticed/config.json (XDG-compliant).

noticed mcp

noticed mcp                        # bridge stdio to the canonical hosted MCPnoticed mcp --log-level debug      # include proxy debug logging on stderr

noticed completion <shell>

noticed completion bash >> ~/.bashrcnoticed completion zsh >> ~/.zshrcnoticed completion fish > ~/.config/fish/completions/noticed.fish

Environment variables

Precedence: CLI flags > environment variables > config file.

MCP tools

The hosted server is the source of truth for the current direct-tool surface. Clients discover ordinary tools such as search_people, get_person, network_summary, mission and goal operations, lists and views, memories, interactions, and schedules through the standard tools/list request. The stdio bridge forwards discovery and invocation without maintaining a second registry.

Test with the MCP Inspector:

# stdio bridge to the same hosted servernpx @modelcontextprotocol/inspector npx @noticed/cli mcp
# hosted (Streamable HTTP) — set Authorization: Bearer <key> in the inspector UInpx @modelcontextprotocol/inspector# URL: https://mcp.noticed.so/api/mcp

Or by hand against the stdio bridge:

echo '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | noticed mcpecho '{"jsonrpc":"2.0","method":"tools/list","id":2}' | noticed mcp

Programmatic usage

import { NoticedApiClient } from "@noticed/cli";
const client = new NoticedApiClient({  baseUrl: "https://www.noticed.so",  apiKey: "nk_live_…",});
const results = await client.search("AI engineers", { limit: 10 });const path = await client.path({ to: results.hits[0]?.github_user_id });
console.log(results.hits, path);

Development

npm installnpm run buildnpm testnpm run lintnpm 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 heavier; most users want the hosted service.

If you do run your own instance, set NOTICED_MCP_URL to its Streamable HTTP MCP endpoint. For a standard deployment, NOTICED_API_URL also works and the CLI derives /api/mcp:

export NOTICED_API_URL=https://noticed.your-domain.comexport NOTICED_API_KEY=nk_live_…noticed search "AI engineers"noticed mcp

The source for the hosted service lives at https://github.com/noticedso/noticed.

License

MIT © noticed