MCP Server and Client

MCP Server and Client

Relevant source files

The following files were used as context for generating this wiki page:

• cmd/axis/mcp_client.go
• cmd/axis/mcp_client_test.go
• docs/future/hybrid-orchestration-spec.md
• examples/mcp-event-client/README.md
• examples/mcp-event-client/main.go
• internal/daemon/daemon.go
• internal/daemon/daemon_test.go
• internal/events/events_test.go
• internal/events/logger.go
• internal/mcp/degraded_contract_test.go
• internal/mcp/doc.go
• internal/mcp/doc_test.go
• internal/mcp/freshness_test.go
• internal/mcp/server.go
• internal/mcp/server_test.go
• internal/mcp/server_tools_test.go
• internal/mcp/session_cache.go
• internal/mcp/session_cache_test.go
• internal/mcp/triangle.go
• internal/mcp/triangle_test.go
• internal/mcpclient/call.go
• internal/mcpclient/connection.go
• internal/mcpclient/registry.go
• internal/mcpclient/registry_test.go
• internal/models/id.go
• internal/models/id_test.go

AXIS implements the Model Context Protocol (MCP) to expose cluster state and advisory capabilities to AI agents and external tools. This implementation consists of a high-performance MCPServer that integrates directly with the AXIS daemon and a flexible mcpclient for connecting to external MCP ecosystems.

The AXIS MCP implementation is designed with a Defense in Depth philosophy: while it provides rich advisory metadata (e.g., ReadOnlyHint), the authoritative security boundary remains the internal/safety and internal/execution layers internal/mcp/doc.go:4-21.

MCPServer Architecture

The MCPServer is an experimental diagnostic surface that provides read-only access to the ClusterSnapshot and enables advisory resource orchestration via the "Triangle" protocol.

Core Components and Data Flow

The server utilizes a SessionCache to ensure that AI agents receive consistent, point-in-time views of the cluster during a conversation, while also supporting push-based updates when the cluster state changes.

graph TD
    subgraph "Code Entity Space: internal/mcp"
        Server["NewServer() [server.go]"]
        SCache["SessionCache [session_cache.go]"]
        TTools["Triangle Tools [triangle.go]"]
        RTools["Resource Tools [server.go]"]
    end

    subgraph "Natural Language Space"
        Daemon["AXIS Daemon"]
        Ledger["Resource Ledger"]
        Agent["AI Agent (Client)"]
    end

    Agent -- "JSON-RPC" --> Server
    Server -- "InvalidateAll()" --> SCache
    Daemon -- "OnSnapshotChanged" --> Server
    Server -- "Fetch" --> SCache
    SCache -- "currentSnapshot()" --> Daemon
    TTools -- "Lock & Reserve" --> Ledger
    RTools -- "Read" --> SCache

Loading

Sources: internal/mcp/server.go:87-137, internal/mcp/session_cache.go:21-36, internal/mcp/triangle.go:101-184

Session Cache and Invalidation

To prevent "hallucination" caused by shifting cluster states during a single reasoning loop, the SessionCache internal/mcp/session_cache.go:21-27 manages per-session snapshots:

• TTL-based Refresh: Entries expire after a configurable duration (default 30s) internal/mcp/session_cache.go:29-36.
• Daemon Hooks: The server registers a SnapshotChangedFunc with the daemon to call InvalidateAll() whenever a new ClusterSnapshot is assembled internal/mcp/server.go:107-110.
• Session Lifecycle: When an MCP session is unregistered, its specific cache entry is purged via Invalidate(sessionID) internal/mcp/server.go:102-105.

Advisory Tools and Resources

The server exposes several tools and resources that allow agents to reason about the cluster without granting them direct execution authority.

Cluster Resources

• cluster://snapshot: A JSON resource providing the full ClusterSnapshot, including node health, hardware specs, and resident models internal/mcp/server.go:140-149.
• Event Interests: A lightweight registry for agents to express interest in specific cluster events internal/mcp/server.go:31-51.

Diagnostic and Placement Tools

Tool Name	Purpose	Implementation
placement_decision	Predicts where a task would run based on current facts.	internal/mcp/server.go:163-177
ssh_connectivity_test	Validates SSH paths to remote nodes.	internal/mcp/server.go:252-263
axis_health	Returns the daemon health and warning payload.	internal/mcp/server.go:179-188
ip_addr / tailscale_status	Local networking diagnostics for the host node.	internal/mcp/server.go:200-215

Sources: internal/mcp/server.go:151-265

Triangle Advisory Leases

The "Triangle" protocol allows agents to request advisory resource leases. These are entries in the reservation.Ledger that signal intent to use resources (RAM/VRAM), preventing overcommit by other agents or CLI users.

sequenceDiagram
    participant A as AI Agent
    participant S as MCP Server
    participant L as reservation.Ledger
    participant D as ClusterSnapshot

    A->>S: triangle_request_lease(node, ram_mb)
    S->>D: Get current snapshot
    Note over S,D: Check if snapshot is stale (>30s)
    S->>L: LockFile()
    S->>L: Reserve(entry)
    L-->>S: Reserved Entry
    S->>L: UnlockFile()
    S-->>A: Lease ID + Expiry

Loading

Sources: internal/mcp/triangle.go:101-184, internal/mcp/triangle_test.go:41-77

Lease Management Functions

• triangle_request_lease: Acquires a file-system lock on ledger.json, validates capacity against the latest snapshot, and creates a timed reservation internal/mcp/triangle.go:101-184.
• triangle_heartbeat_lease: Extends the ExpiresAt timestamp of an active lease to prevent reclamation internal/mcp/triangle.go:214-230.
• triangle_release_lease: Explicitly removes a reservation from the ledger internal/mcp/triangle.go:186-212.

MCP Client

The mcpclient package allows AXIS to act as a client to external MCP servers configured in nodes.yaml. This enables the AXIS Agent to consume tools from the broader MCP ecosystem (e.g., filesystem tools, browser automation).

Implementation Details

• Transport Support: Currently supports stdio transport for sub-process MCP servers cmd/axis/mcp_client.go.
• Registry: Manages a collection of active connections to external servers defined in the MCPServers configuration block cmd/axis/mcp_client_test.go:43-52.
• CLI Integration: Commands like axis mcp list, axis mcp tools, and axis mcp call provide a direct interface for debugging external server integrations cmd/axis/mcp_client_test.go:12-111.

Sources: cmd/axis/mcp_client.go, cmd/axis/mcp_client_test.go:1-112

---