---
name: ck-mcp-management
description: Manage MCP servers — discover, analyze, and execute tools, prompts, and resources. Use for MCP integrations, intelligent tool selection, multi-server management, context-efficient capability discovery, MCP client implementation.
---

# ck-mcp-management

Manage and interact with Model Context Protocol (MCP) servers. Discover capabilities, select relevant tools, and execute them without polluting the main context window. Embeds the `mcp-manager` agent role.

## When to Use

- Discovering available tools from configured MCP servers
- Selecting which MCP tools are relevant for a specific task
- Executing MCP tools programmatically
- Building or debugging MCP client implementations
- Keeping main context clean by delegating MCP operations

## Don't Use When

- The required tool is a standard file or code operation — use native tools directly
- MCP servers are not configured in the environment
- Simple tasks that don't require external tool capabilities

## Execution Priority

1. **Gemini CLI** (primary): Check if `gemini` CLI is available; execute via stdin piping
2. **Direct Scripts** (secondary): Use CLI scripts for specific tool/server control
3. **Report Failure**: If both fail, report error with actionable guidance

**IMPORTANT:** Always use stdin piping with Gemini CLI, NOT the `-p` flag (deprecated, skips MCP initialization):
```bash
# Correct
echo "<task description>" | gemini -y -m <model>

# Wrong — skips MCP init
gemini -p "<task description>"
```

## Core Capabilities

### 1. Gemini CLI Execution (Primary)

```bash
# Check availability
command -v gemini >/dev/null 2>&1 || exit 1

# Setup symlink if needed
[ ! -f .gemini/settings.json ] && mkdir -p .gemini && ln -sf $HOME/.claude/.mcp.json .gemini/settings.json

# Execute task
echo "<task description>. Return JSON only per GEMINI.md instructions." | gemini -y -m <model>
```

Expected output (structured JSON):
```json
{"server":"name","tool":"name","success":true,"result":<data>,"error":null}
```

### 2. Script Execution (Fallback)

```bash
# List all available tools (saves to assets/tools.json)
npx tsx scripts/cli.ts list-tools

# Execute a specific tool
npx tsx scripts/cli.ts call-tool <server> <tool> '<json-args>'
```

### 3. Capability Discovery

```bash
npx tsx scripts/cli.ts list-tools      # Saves catalog to assets/tools.json
npx tsx scripts/cli.ts list-prompts
npx tsx scripts/cli.ts list-resources
```

## Workflow

1. **Receive task** from main agent
2. **Check Gemini CLI** availability
3. **Execute**:
   - Gemini available: `echo "<task>" | gemini -y -m <model>`
   - Gemini unavailable: `npx tsx scripts/cli.ts call-tool <server> <tool> <args>`
4. **Report** concise summary back: status, output, artifact paths, any errors

## Configuration

MCP servers configured in `$HOME/.claude/.mcp.json`.

**Gemini CLI integration:** Create symlink so Gemini auto-loads MCP config:
```bash
mkdir -p .gemini && ln -sf $HOME/.claude/.mcp.json .gemini/settings.json
```

**GEMINI.md:** Project root file that Gemini CLI auto-loads, enforcing structured JSON responses. Ensures parseable, consistent output instead of unpredictable natural language.

## Tool Catalog

The `list-tools` command persists a complete catalog to `assets/tools.json` with full schemas. The LLM reads this catalog directly to select relevant tools — better than keyword matching.

## Integration Patterns

- **Pattern 1**: Gemini CLI auto-execution (fastest, automatic tool discovery)
- **Pattern 2**: Direct script execution (manual tool/server specification)
- **Pattern 3**: LLM-driven tool selection from `assets/tools.json` catalog
- **Pattern 4**: Multi-server orchestration across configured servers

## Output Format

```
Method: Gemini CLI / Direct Script
Status: success / failure
Result: [output or artifact paths]
Error: [if any, with actionable guidance]
```

**IMPORTANT:** Sacrifice grammar for concision. List unresolved questions at end if any.