AI Tooling

This guide covers setting up AI assistants and MCP servers for development workflows.

Prerequisites

Claude Code installed (brew install anthropic-cli/tap/claude-code)
Vault access configured (see Environment Setup)
Network access to cluster services

Claude Code Setup

Claude Code is the primary AI assistant for this repository.

Configuration Files

File	Purpose
`CLAUDE.md`	Repository-specific instructions
`~/.claude/CLAUDE.md`	User-wide preferences
`~/.claude/mcp.json`	MCP server configuration

Key Skills

Skills are invoked via the Skill tool. Check for applicable skills before responding:

Skill	Use Case
`superpowers:brainstorming`	Feature planning and design
`superpowers:systematic-debugging`	Bug investigation
`superpowers:writing-plans`	Multi-step implementation
`superpowers:using-git-worktrees`	Isolated feature development
`commit-commands:commit`	Git commits
`pr-review-toolkit:review-pr`	PR reviews
`grafana`	Dashboard, Loki logs, Prometheus queries

MCP Servers

Model Context Protocol servers extend Claude’s capabilities.

Active Servers

Server	Purpose	Priority
Filesystem	File read/write operations	MUST use for file ops
Kubernetes	Cluster investigation (readonly)	Pods, logs, events
Terraform	State and workspace operations	Terraform Cloud
Exa	Intelligent web search	Research
Firecrawl	Web scraping	Content extraction
Context7	Library documentation	API docs

MCP Configuration

MCP servers can be configured at two levels:

Location	Scope	Use Case
`~/.claude.json`	Global (all projects)	Personal MCP servers
`.mcp.json`	Project-specific	Repository-shared MCP servers

Add to ~/.claude.json (global) or .mcp.json (project root):

{
  "mcpServers": {
    "kubernetes-mcp-server": {
      "command": "mcp-k8s",
      "args": ["--context", "fzymgc-house"]
    },
    "grafana": {
      "command": "mcp-grafana",
      "env": {
        "GRAFANA_URL": "https://grafana.fzymgc.house",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<token-from-vault>"
      }
    }
  }
}

Grafana MCP Server

Local installation:

go install github.com/grafana/mcp-grafana/cmd/mcp-grafana@latest

Get token from Vault:

# Viewer token (recommended for most operations)
vault kv get -field=viewer_token secret/fzymgc-house/cluster/grafana/mcp-server

# Editor token (when modifications needed)
vault kv get -field=editor_token secret/fzymgc-house/cluster/grafana/mcp-server

Grafana MCP capabilities:

Tool	Purpose
`search_dashboards`	Find dashboards by name/tag
`get_dashboard_by_uid`	Retrieve dashboard JSON
`list_datasources`	List configured data sources
`query_prometheus`	Execute PromQL queries
`query_loki`	Execute LogQL queries

Remote MCP (In-Cluster)

Connect to the in-cluster MCP server:

{
  "mcpServers": {
    "grafana": {
      "type": "streamable-http",
      "url": "https://mcp.grafana.fzymgc.house/mcp",
      "headers": {
        "Authorization": "Bearer <token-from-vault>"
      }
    }
  }
}

For the in-cluster agentgateway MCP gateway (aggregating multiple upstream MCP servers — engram via Keycloak OAuth (dynamic client registration), SaaS servers via virtual key), see MCP Gateway Clients.

Workflow Integration

Development Workflow

Use superpowers:brainstorming before new features
Create worktree with superpowers:using-git-worktrees
Use superpowers:writing-plans for implementation
Request review with pr-review-toolkit:review-pr

Cluster Operations

Use Kubernetes MCP for investigation (pods, logs, events)
Do NOT apply changes directly - ArgoCD manages deployments
Use grafana skill for dashboard and Loki log queries

Key Directives

Rule	Reason
MUST use feature branches	Never commit to main
MUST check skills before responding	Even 1% chance → invoke skill
MUST use Filesystem MCP for file ops	Saves context vs native tools
MUST NOT apply kubectl changes	ArgoCD manages deployments

Verification

Test MCP server connectivity:

# Verify Kubernetes MCP
kubectl --context fzymgc-house get nodes

# Verify Grafana access
vault kv get secret/fzymgc-house/cluster/grafana/mcp-server