Architecture Overview

Alien Giraffe observes and governs the MCP traffic generated by AI agents across a fleet. It has a central control plane and a per-endpoint agent, connected by a small, signed reporting API.

Components at a glance

flowchart TB
  subgraph Endpoints["Managed endpoints"]
    direction LR
    subgraph E1["Endpoint"]
      A1["AI agents"] --> L1["Lander"]
      L1 --> M1["MCP servers"]
    end
    subgraph E2["Endpoint"]
      A2["AI agents"] --> L2["Lander"]
      L2 --> M2["MCP servers"]
    end
  end
  L1 -->|register · inventory · events| API
  L2 -->|register · inventory · events| API
  subgraph ControlPlane["Control plane (AlienGiraffe Connector)"]
    API["REST API\n/v1 + /admin"]
    DB[("Postgres")]
    Dash["Dashboard"]
    API --> DB --> Dash
  end

• Control plane & endpoint agent — what each side is responsible for and where the trust boundary sits.
• Devices & fleet — how endpoints become tracked devices and roll up into fleet views.
• AI agents — the agent types Alien Giraffe discovers and how.
• MCP servers — the MCP registry, transports, and adoption metrics.
• MCP mirroring — how Lander proxies traffic to capture every tool call.
• Observability events — the telemetry model that powers the dashboards.
• Security & audit — device identity, signing, RBAC, and audit logging.

The reporting pipeline

The endpoint agent and control plane communicate through three idempotent, signed steps:

sequenceDiagram
  participant L as Lander (endpoint)
  participant API as Control plane API
  L->>API: POST /v1/devices/register (cert, serial, owner)
  API-->>L: deviceId + cert fingerprint
  L->>API: POST /v1/devices/inventory (agents + their MCPs)
  API-->>L: accepted (agentsIn, mcpsIn)
  loop per MCP tool call
    L->>API: POST /v1/devices/events (batch of observability events)
    API-->>L: accepted
  end

1. Register — on startup the endpoint proves its identity with a self-signed device certificate and is assigned a deviceId.
2. Inventory — it reports which agents are installed and which MCPs each one is configured to use (names and transports only — never secrets).
3. Events — as agents call MCP tools, Lander streams observability events describing each call and its policy outcome.

Every request is signed with the device key, so the control plane can attribute and verify the source. See Security & audit for the trust model.

Where to go next

If you operate the platform, start with the control plane install guide and then the Lander install guide. If you’re modeling the data, read Observability events and the event schema reference.