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>"
      }
    }
  }
}

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