resume-site/MCP-SETUP.md

# MCP Server Setup Guide

## What is MCP?

Model Context Protocol (MCP) is a standard for connecting AI assistants like Claude to external tools and data sources. Your cluster has MCP servers that provide programmatic access to services like Gitea.

## MCP Servers in Your Cluster

Currently running MCP servers:

```bash
kubectl get svc -n mcp
```

- **mcp-ecosystem-gitea-mcp** (10.43.80.98:3014)
- **mcp-umbrella-gitea-mcp** (10.43.241.50:3014)

## How to Connect MCP to Claude Code

To make MCP tools available in Claude Code sessions, you need to configure the MCP server connection in your Claude Code settings.

### Method 1: Claude Code Configuration File

Create or edit `~/.config/claude-code/mcp.json` (or the appropriate config location):

```json
{
  "mcpServers": {
    "gitea": {
      "url": "http://10.43.241.50:3014",
      "token": "your-mcp-token-here",
      "description": "Gitea MCP server for repository management"
    }
  }
}
```

### Method 2: Environment Variables

Set MCP server configuration via environment variables:

```bash
export MCP_GITEA_URL="http://10.43.241.50:3014"
export MCP_GITEA_TOKEN="your-mcp-token-here"
```

### Method 3: Port Forward for Local Access

If Claude Code runs locally (not in the cluster):

```bash
# Forward the MCP server port to localhost
kubectl port-forward -n mcp svc/mcp-umbrella-gitea-mcp 3014:3014

# Then configure Claude Code to use localhost:3014
```

## MCP Token Management

### Where to Find MCP Tokens

1. **Check Kubernetes Secrets:**
   ```bash
   kubectl get secrets -n mcp
   kubectl get secret -n mcp <secret-name> -o yaml
   ```

2. **Generate New Token:**
   If your MCP server supports token generation, you can create new tokens via its API or management interface.

### Token Security

- MCP tokens are sensitive credentials
- Store them securely (use Kubernetes secrets, not in code)
- Rotate tokens periodically
- Use different tokens for different environments

## Available MCP Tools

Once connected, MCP tools will appear in Claude Code with the `mcp__` prefix, such as:

- `mcp__gitea_create_repo` - Create a new repository
- `mcp__gitea_list_repos` - List repositories
- `mcp__gitea_push` - Push code to a repository
- `mcp__gitea_webhook` - Manage webhooks

(Actual tool names depend on your MCP server implementation)

## Using MCP in Future Deployments

When you have MCP properly configured, Claude Code can automatically:

1. **Create Gitea repositories** without manual API calls
2. **Push code** without entering credentials
3. **Trigger builds** by calling webhooks
4. **Monitor deployment** status
5. **Update configurations** in the cluster

### Example Workflow with MCP

```markdown
User: "Deploy my new app to Kubernetes"

Claude will automatically:
1. Use mcp__gitea_create_repo to create the Git repository
2. Use mcp__gitea_push to push the code
3. Use mcp__kubectl_apply to create Kubernetes resources
4. Use mcp__flux_sync to trigger Flux reconciliation
5. Use mcp__kubectl_get to check deployment status
```

## Troubleshooting MCP Connection

### Check if MCP is Connected

In a Claude Code session, MCP tools should appear in the available functions list. They'll start with `mcp__`.

### Connection Issues

1. **MCP server not reachable:**
   ```bash
   curl http://10.43.241.50:3014/health
   ```

2. **Token invalid:**
   - Verify the token hasn't expired
   - Check token permissions
   - Generate a new token

3. **Claude Code not detecting MCP:**
   - Restart Claude Code
   - Check configuration file syntax
   - Verify MCP server is running

### Testing MCP Access

```bash
# Test MCP server is responding
curl -H "Authorization: Bearer YOUR_TOKEN" \
  http://10.43.241.50:3014/api/tools

# Should return list of available MCP tools
```

## Setting Up MCP for Other Services

The same pattern can be used for other services:

### Harbor Registry MCP

```json
{
  "mcpServers": {
    "harbor": {
      "url": "http://harbor-mcp-service:3015",
      "token": "harbor-mcp-token",
      "description": "Harbor registry management"
    }
  }
}
```

### Kubernetes MCP

```json
{
  "mcpServers": {
    "kubernetes": {
      "url": "http://k8s-mcp-service:3016",
      "token": "k8s-mcp-token",
      "description": "Kubernetes cluster management"
    }
  }
}
```

## Benefits of MCP Integration

1. **Automation** - No manual steps for common tasks
2. **Security** - Credentials managed centrally
3. **Efficiency** - Faster deployments
4. **Consistency** - Standardized workflows
5. **Error Reduction** - Less manual intervention

## Future Enhancements

Consider adding MCP servers for:

- **ArgoCD** - GitOps deployments
- **Prometheus** - Metrics and monitoring
- **Vault** - Secrets management
- **Grafana** - Dashboard creation
- **AlertManager** - Alert configuration

## Quick Reference

### Current Setup (Without MCP)
```bash
# Manual steps required:
1. Create Gitea repo via web UI or API
2. Git push with credentials
3. kubectl apply manifests
4. Wait for Flux sync
```

### With MCP Connected
```bash
# Automated via Claude Code:
User: "Deploy this app"
# Claude handles everything automatically
```

## Resources

- [MCP Specification](https://github.com/anthropics/anthropic-mcp)
- [Claude Code Documentation](https://docs.anthropic.com/claude/docs/claude-code)
- Your cluster's MCP server documentation

---

**Note:** The specific MCP tools and configuration format may vary based on your MCP server implementation. Check your MCP server's documentation for exact details.