Skip to main content

​
Two ways to register servers

MethodCommandBest for
Auto-discoverylangsight initDev machines — reads existing IDE configs
Manual registrationlangsight addProduction — adds remote or stdio servers explicitly

​
Auto-discovery — langsight init

langsight init scans every well-known MCP config file location on your machine and merges all discovered servers into .langsight.yaml.

​
Usage

langsight init [OPTIONS]

​
Options

OptionDefaultDescription
--output, -o.langsight.yamlOutput path for config file
--slack-webhook—Slack webhook URL for alerts
--yes, -yfalseSkip confirmation prompts
--skip-checkfalseWrite config without running the first health check

​
All supported IDE clients

LangSight searches the following locations. On macOS and Linux the paths use ~. On Windows they expand to %APPDATA% equivalents.

​
Global user configs

ClientConfig pathNotes
Claude Desktop~/Library/Application Support/Claude/claude_desktop_config.json (macOS)—
Claude Desktop~/.config/claude/claude_desktop_config.json (Linux)—
Claude Desktop%APPDATA%\Claude\claude_desktop_config.json (Windows)—
Cursor~/.cursor/mcp.json—
VS Code~/.vscode/mcp.jsonUses "servers" key, not "mcpServers"
Windsurf~/.windsurf/mcp.json—
Claude Code~/.claude/mcp.json—
Gemini CLI~/.gemini/mcp.json—
Kiro~/.kiro/mcp.json—
Zed~/.config/zed/settings.jsonUses "context_servers" key
Cline~/.cline/mcp.json—

​
Project-local configs

LangSight also checks for project-local config files in the current directory:
FileUsed by
.cursor/mcp.jsonCursor workspace
.mcp.jsonGeneric / shared team config
.vscode/mcp.jsonVS Code workspace
Project-local configs take precedence over global ones when a server name appears in both.

​
Config key variants

Different IDE clients use different keys for their MCP server lists. LangSight handles all variants automatically:
KeyUsed by
mcpServersClaude Desktop, Claude Code, Cursor, Windsurf, Gemini CLI, Kiro, Cline
serversVS Code
context_serversZed

​
Example output

$ langsight init

LangSight Init — scanning for MCP servers...

  Claude Desktop  (~/Library/Application Support/Claude/claude_desktop_config.json)  4 servers
  Cursor          (~/.cursor/mcp.json)                                                2 servers
  VS Code         (~/.vscode/mcp.json)                                                1 server
  .cursor/mcp.json  (project-local)                                                   1 server

Discovered 8 MCP servers (1 duplicate removed):
  1. snowflake-mcp    (stdio)
  2. github-mcp       (stdio)
  3. slack-mcp        (sse)
  4. jira-mcp         (stdio)
  5. postgres-mcp     (stdio)
  6. filesystem-mcp   (stdio)
  7. search-mcp       (stdio)
  8. custom-api       (streamable_http)

Include all 8 servers? [Y/n]: Y

Slack webhook URL for alerts (leave blank to skip):

Running first health check...

  snowflake-mcp    ✓ UP       89ms
  github-mcp       ✓ UP       54ms
  slack-mcp        ✓ UP      142ms
  jira-mcp         ✗ DOWN    —       timeout after 5s
  postgres-mcp     ✓ UP       31ms
  filesystem-mcp   ✓ UP       12ms
  search-mcp       ✓ UP       67ms
  custom-api       ✓ UP       23ms

7/8 servers healthy

Config written to .langsight.yaml
  8 MCP servers configured

​
Skip the first health check

If you want to write the config without waiting for a health check (useful in CI pipelines or during infrastructure setup): 
langsight init --skip-check

​
Non-interactive mode

langsight init --yes \
  --slack-webhook https://hooks.slack.com/services/... \
  --output /etc/langsight/langsight.yaml \
  --skip-check

​
Manual registration — langsight add

langsight add registers a single server — either an HTTP/remote server or a local stdio server. It runs a connection test and shows you the discovered tools before writing to config.

​
Usage

langsight add <name> [OPTIONS]

​
Options

OptionDescription
--urlBase URL for HTTP-based servers (StreamableHTTP or SSE)
--commandCommand to start a stdio server
--argsArgument to pass to the command (repeatable)
--env KEY=VALUEEnvironment variable for the server process (repeatable)
--header KEY=VALUEHTTP header to send with every request (repeatable)
--configPath to .langsight.yaml to update (default: auto-discovered)
--skip-checkAdd to config without running a connection test

​
Register a remote HTTP server

# Production server, no auth
langsight add postgres-mcp --url https://postgres-mcp.internal.company.com/mcp

# With authorization header
langsight add github-mcp \
  --url https://github-mcp.prod.company.com/mcp \
  --header "Authorization=Bearer $GITHUB_TOKEN"

# Multiple headers
langsight add analytics-mcp \
  --url https://analytics-mcp.company.com/mcp \
  --header "Authorization=Bearer $TOKEN" \
  --header "X-Tenant-ID=acme"
Expected output: 
Testing connection to github-mcp...

  Connected in 67ms
  Discovered 12 tools:
    create_issue, update_issue, close_issue, list_issues,
    create_pr, merge_pr, list_prs, get_commit, list_commits,
    search_code, create_branch, delete_branch

Add github-mcp to .langsight.yaml? [Y/n]: Y

  Added github-mcp to .langsight.yaml
  Run: langsight mcp-health --server github-mcp

​
Register a local stdio server

# Python server
langsight add local-db \
  --command "uv run python server.py" \
  --args "--db-url postgresql://localhost/mydb"

# npx-based server with environment variables
langsight add my-server \
  --command "npx -y @scope/server" \
  --env "API_KEY=$MY_API_KEY" \
  --env "ENV=production"

# Multiple --args flags (each is one argument token)
langsight add custom-mcp \
  --command "python" \
  --args "-m" \
  --args "mcp_server" \
  --args "--port 5000"

​
When the connection test fails

If the server is unreachable, langsight add shows the error and asks whether to add it anyway: 
Testing connection to jira-mcp...

  Connection failed: timeout after 5s

Add anyway? This server will appear as DOWN until it becomes reachable.
Add jira-mcp? [y/N]: y

  Added jira-mcp to .langsight.yaml (status: unverified)
This is useful when you want to pre-configure a server that isn’t running yet.

​
Skip the connection test

langsight add jira-mcp \
  --command "uv run python jira_mcp/server.py" \
  --skip-check

​
Generated config

Both langsight init and langsight add write to .langsight.yaml. The schema is identical regardless of how the entry was added: 
servers:
  # HTTP server with auth header
  - name: github-mcp
    transport: streamable_http
    url: https://github-mcp.prod.company.com/mcp
    headers:
      Authorization: "Bearer ${GITHUB_TOKEN}"

  # stdio server
  - name: postgres-mcp
    transport: stdio
    command: uv run python server.py
    args:
      - --db-url
      - postgresql://localhost/mydb
    env:
      PG_PASSWORD: "${PG_PASSWORD}"

  # SSE server (legacy transport)
  - name: legacy-mcp
    transport: sse
    url: http://localhost:8080/sse

alerts:
  slack_webhook: "${SLACK_WEBHOOK_URL}"
Environment variables in ${VAR} syntax are expanded from the process environment at runtime. Never commit actual secrets to this file.