Skip to main content

Connect Your Agents

Once Watchlight Beacon is running, connect your AI agents and MCP servers so they can be discovered, registered, and governed.

Docker Network Discovery​

The simplest approach: add your containers to the beacon-partner Docker network. wl-discover will automatically find and register them.

# your-project/docker-compose.yml
services:
  my-agent:
    image: my-agent:latest
    networks: [default, beacon-partner]

  my-mcp-server:
    image: my-mcp-server:latest
    networks: [default, beacon-partner]

networks:
  beacon-partner:
    external: true

wl-discover scans the beacon-partner network, probes ports for MCP servers, and detects agent frameworks (LangGraph, CrewAI, AutoGen, LangChain) using a multi-tier detection model.

Self-Registration via API​

Register agents manually when automatic discovery isn't suitable:

curl -k -X POST https://localhost:8443/api/v1/agents/register \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "my-research-agent",
    "agent_type": "autonomous",
    "description": "Investment research agent using LangGraph"
  }'

The response includes an api_key for subsequent authenticated requests.

MCP Server Registration​

Register MCP servers with their capabilities:

curl -k -X POST https://localhost:8443/api/v1/servers/register \
  -H 'Content-Type: application/json' \
  -H 'X-Scanner-ID: scanner-001' \
  -H 'X-API-Key: your-scanner-key' \
  -d '{
    "name": "web-search-mcp",
    "url": "http://my-mcp-server:3000",
    "capabilities": {
      "tools": [
        {"name": "search_web", "description": "Search the web"}
      ]
    }
  }'

Heartbeats​

Registered servers must send periodic heartbeats to maintain their lease. Servers that stop heartbeating are automatically marked as stale and eventually removed.

curl -k -X POST https://localhost:8443/api/v1/servers/heartbeat \
  -H 'Content-Type: application/json' \
  -H 'X-Scanner-ID: scanner-001' \
  -H 'X-API-Key: your-scanner-key' \
  -d '{"server_id": "your-server-id"}'

wl-discover handles heartbeats automatically for discovered servers.

Tier 3: Routing Through the Governance Proxy​

When running Tier 3, route your agent's API calls through wl-proxy for policy enforcement and credential injection:

services:
  my-agent:
    networks: [default, beacon-partner]
    environment:
      OPENAI_BASE_URL: https://proxy-openai:9443/v1   # Route through proxy
      REQUESTS_CA_BUNDLE: /certs/beacon-ca.crt         # Trust self-signed CA
      # No OPENAI_API_KEY needed — wl-secrets-broker injects it
    volumes:
      - ./beacon-ca.crt:/certs/beacon-ca.crt:ro

networks:
  beacon-partner:
    external: true

No code changes required — just set the base URL environment variable.

Verify Connectivity​

Check that your agents appear in the registry:

# List all registered servers
curl -k https://localhost:8443/api/v1/servers

# List all registered agents
curl -k https://localhost:8443/api/v1/agents

Or open the Registry Dashboard at https://localhost:8443 and navigate to the Topology view for an interactive graph of agent-server connections.