MCP for AI Agents

faros exposes your edges as Model Context Protocol (MCP) servers. AI coding assistants — Claude Code, Claude Desktop, Codex, Cursor, anything that speaks MCP — can list pods, describe deployments, run commands, and (with the edges provider’s service catalog) even control apps like Home Assistant across all your edges at once.

There are two endpoint shapes:

Exactly one of the two flags is required.

Get the URL

kubectl faros mcp url --mcpserver-name default

This prints the endpoint URL plus ready-to-paste setup snippets for Claude Code (claude mcp add), Claude Desktop (claude_desktop_config.json), and Codex (codex mcp add), with your bearer token filled in.

The URL shapes look like this:

# Aggregate (MCPServer object)
https://<hub>/services/mcpserver/<cluster>/apis/faros.sh/v1alpha1/mcpservers/<name>/mcp

# Per-edge Kubernetes (served by the edges provider)
https://<hub>/services/providers/edges/agent/<cluster>/apis/edges.faros.sh/v1alpha1/kubernetesclusters/<edge>/mcp

<cluster> is your workspace’s logical cluster ID — the CLI derives it from your kubeconfig, so you never construct these by hand.

Adding to Claude Code

Paste the printed claude mcp add line straight into your shell:

claude mcp list        # confirm it's registered

For Claude Desktop, add the printed JSON snippet under mcpServers in claude_desktop_config.json and restart the app. For Codex, use the printed codex mcp add line. If the target is a Linux/server edge, use --mcpserver-name and let the aggregate endpoint expose its SSH tools; --edge accepts Kubernetes edges only.

The MCPServer object

The aggregate endpoint is backed by an MCPServer custom resource (faros.sh/v1alpha1) in your workspace; the hub creates one named default in every new workspace. The current resource supports a display name, client instructions, and a readOnly hint. It does not currently have an edge label-selector field. Use separate named servers when you need distinct client-facing instructions:

kubectl get mcpservers.faros.sh

apiVersion: faros.sh/v1alpha1
kind: MCPServer
metadata:
  name: audit
spec:
  displayName: Read-only audit assistant
  readOnly: true
  instructions: Ask before any operation that could change production state.

Apply it in the selected workspace, then obtain its endpoint with kubectl faros mcp url --mcpserver-name audit.

Check provisioning and tool discovery without printing the token:

kubectl get mcpserver audit -o jsonpath='{.status.phase}{"\n"}{.status.conditions[*].message}{"\n"}'
kubectl get mcpserver audit -o jsonpath='{range .status.federatedProviders[*]}{.name}{" reachable="}{.reachable}{"\n"}{end}'

Authentication for the aggregate endpoint uses a long-lived service-account token minted per MCPServer (referenced from status.tokenSecretRef) rather than your personal OIDC token — so long-running MCP connections don’t break when your browser token expires.

What tools are exposed

The aggregate endpoint federates tools from two sources:

• Edges: Kubernetes tools (via kubernetes-mcp-server ) for every connected Kubernetes edge, Linux/SSH tools for server edges, and per-service tools for any Service the edges provider has discovered (e.g. ha_call_service for Home Assistant).
• Providers: every enabled provider that exposes MCP contributes its tools, namespaced as <provider>__<tool> — e.g. code__create_repository, kuery__kuery_query, infrastructure__provision.

Authentication and scoping

The aggregate endpoint uses its MCPServer service-account credential. Do not assume that it is identical to your personal session’s effective permissions. Before handing an endpoint to an assistant, inspect the endpoint’s status.federatedProviders, verify an allowed operation and a denied operation, and treat readOnly as a client/tooling hint. The current hub implementation provisions a broad placeholder role for the MCP service account, so readOnly: true is not a server-side authorization boundary; keep sensitive endpoints private and follow the service accounts guidance.

To rotate an MCP credential, delete the MCPServer and recreate it with the same or a new name. Its owned ServiceAccount, token Secret, and binding are garbage-collected with the resource; wait for the replacement to reach Ready and update the client with a newly generated mcp url command. Revoke the old client configuration immediately after the replacement is working.