MCP Servers Overview

Architecture and design of the Federal Frontier Platform’s MCP server fleet — 12 servers, 150+ tools, all discoverable by Compass.

What Is MCP?

The Model Context Protocol (MCP) is a lightweight JSON-RPC 2.0 interface that lets an LLM-powered application discover and invoke tools exposed by backend services. Each MCP server publishes a manifest of tools (name, description, input schema) and handles execution requests. The protocol defines two core methods:

MCP is transport-agnostic. The Federal Frontier Platform uses HTTP POST to /jsonrpc (JSON-RPC 2.0) as the primary transport for server-to-server communication. Some servers also support SSE (Server-Sent Events) for streaming use cases.

Platform Architecture

The platform operates 12 MCP servers exposing over 150 tools across infrastructure, identity, observability, compliance, and ontology domains. Every server runs as a standalone pod in the f3iai Kubernetes namespace.

Request Flow

1. Discovery — At startup, Compass API iterates the MCP_SERVERS registry and calls tools/list on each server. Tool manifests are cached in memory.
2. Selection — When a user sends a chat message, Compass passes the message plus all tool manifests to the LLM. The LLM decides which tool (if any) to call and constructs the arguments.
3. Execution — Compass API sends a tools/call JSON-RPC POST to the appropriate MCP server’s /jsonrpc endpoint.
4. Response — The MCP server executes the tool (querying TypeDB, SSH-ing to a hypervisor, calling a REST API, etc.) and returns the result as a JSON-RPC response.
5. Synthesis — The LLM receives the tool result and generates a natural-language answer for the user.

Example JSON-RPC Exchange

Request (tools/call):

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "ffo.entity.get",
    "arguments": {
      "entity_type": "cluster",
      "entity_name": "fmc"
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"type\": \"cluster\", \"name\": \"fmc\", \"attributes\": {\"environment\": \"production\", ...}}"
      }
    ]
  }
}

Server Registry

MCP servers are registered in two places:

1. PostgreSQL mcp_servers table — Stores the server name, base URL, port, and description. Used by Compass API at startup to know which servers to discover.
2. MCP_SERVERS dict in mcp_tools.py — A Python dictionary in the Compass API codebase that maps server keys to their connection details. This is the runtime source of truth for tool routing.

To add a new server, you must update both locations. See Building a New MCP Server for the full procedure.

Server Inventory

Health and Readiness

Every MCP server exposes standard Kubernetes probe endpoints:

• /health — Liveness probe. Returns 200 if the process is running.
• /ready — Readiness probe. Returns 200 only if the server can reach its backing service (TypeDB, SSH target, REST API, etc.).

These endpoints are wired into the Kubernetes deployment manifests as livenessProbe and readinessProbe respectively.

Observability

MCP servers expose Prometheus metrics at /metrics. Common metrics include:

• mcp_requests_total — Counter of tool invocations, labeled by tool name and status.
• mcp_request_duration_seconds — Histogram of tool execution time.
• Backend-specific counters (e.g., ffo_mcp_typedb_queries_total for FFO).

Grafana dashboards in the platform consume these metrics for alerting and capacity planning.