Cli

@noticed/cli

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/cli
noticed 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/cli@0.4.0 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 installation
npx skills add noticedso/cli --list

# Install globally for Codex and Claude Code
npx 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 credentials
noticed config --set-key nk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# 3. Search your network
noticed search "react developers"

# 4. Find the shortest path to a specific person
noticed path @sarahml
noticed path --li sarah-chen

# 5. JSON output for scripting
noticed 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 language
noticed search "@sarahml"                      # GitHub username
noticed search "CTO at Vercel"                 # job title + company
noticed search "kubernetes" --source github    # filter by source
noticed search "react" --limit 10 --json       # paginated JSON output
noticed search "engineers" --csv > out.csv     # CSV export
noticed 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 login
noticed path 12345                # by github_user_id
noticed path --li sarah-chen      # by LinkedIn username
noticed 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 config
noticed config --set-url <url>     # set API URL
noticed config --set-key <key>     # set API key
noticed 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 MCP
noticed mcp --log-level debug      # include proxy debug logging on stderr

noticed completion <shell>

noticed completion bash >> ~/.bashrc
noticed completion zsh >> ~/.zshrc
noticed 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 server
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 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 mcp
echo '{"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 install
npm run build
npm test
npm run lint
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 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.com
export 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