Skip to main content
LangSight auto-discovers agents and MCP servers from your trace data. No manual catalog registration needed — instrument your agent, send spans, and the catalog populates itself.

​
How it works

When spans arrive at POST /api/traces/spans, LangSight inspects each span’s agent_name and server_name fields. Any value not already in the catalog is automatically registered: 
Agent sends span →  POST /api/traces/spans
                         │
                         ├── agent_name="analyst" not in catalog?
                         │   └── auto-register with description "Auto-discovered from traces"
                         │
                         └── server_name="postgres-mcp" not in catalog?
                             └── auto-register with description "Auto-discovered from traces"
This is best-effort and fail-open — if registration fails, the span is still stored. Your tracing is never blocked by catalog operations.

​
Zero-config setup

There is nothing to configure. Auto-discovery is always on. As soon as you send your first span, the Agents page and Servers page in the dashboard populate automatically. 
from langsight.sdk import LangSightClient
from langsight.integrations.langchain import LangSightLangChainCallback

client = LangSightClient(url="http://localhost:8000", project_id="my-project")

# Auto-detect mode — agent names discovered from graph names
cb = LangSightLangChainCallback(client=client, session_id="sess-001", trace_id="trace-001")

# First run populates the catalog
await supervisor.ainvoke(input, config={"callbacks": [cb]})
# "supervisor", "analyst", "postgres-mcp" etc. now appear in the dashboard

​
Batch backfill

Already have trace data in ClickHouse but the catalog is empty? Use the batch discover endpoints to scan all historical spans and register everything at once.

​
Discover agents

curl -X POST http://localhost:8000/api/agents/discover \
  -H "X-API-Key: ls_your_key"
Response: 
{
  "discovered": 3,
  "agents": ["supervisor", "analyst", "billing-agent"]
}

​
Discover servers

curl -X POST http://localhost:8000/api/servers/discover \
  -H "X-API-Key: ls_your_key"
Response: 
{
  "discovered": 4,
  "servers": ["postgres-mcp", "jira-mcp", "slack-mcp", "openai"]
}
Both /discover endpoints require admin role. They scan ClickHouse for all distinct agent_name and server_name values and register any that are missing from the catalog.

​
What gets registered

CatalogField scannedInitial descriptionStatus
Agentsspan.agent_name”Auto-discovered from traces”active
Serversspan.server_name”Auto-discovered from traces”—
Auto-discovered entries have a generic description. Update them in the dashboard under Agents or MCP Servers to add meaningful descriptions, tags, and runbook URLs.

​
In-process deduplication

The span ingestion endpoint maintains an in-memory set of already-seen agent and server names. A name is only registered once per API process lifetime, avoiding redundant database writes on every span.

​
When to use manual registration instead

Auto-discovery is sufficient for most setups. Use manual registration (PUT /api/agents/metadata/{name}) when you need:
  • Custom descriptions or runbook URLs before the first span arrives
  • Tags for filtering (e.g., ["production", "critical"])
  • Pre-populating the catalog for a new project before agents are deployed