git:20251217.6dea861 to git:20261028.c2c0bcf

9 added, 208 removed. Audit B to B.

---

name: working-with-mcp

description: Use when user mentions MCPProxy/MCP tools (e.g., "check buildkite mcp", "use slack mcp") or when you need to discover or call tools through MCPProxy - immediately checks if mcp__MCPProxy__* tools are available, suggests /mcp reconnect if missing (MCPProxy MCP server not connected), explains when to use MCP tools vs HTTP API for debugging

---

# Working with MCPProxy and MCP Tools

- ## Overview

- MCPProxy can be accessed two ways:

- 1. **MCP Tools** (`mcp__MCPProxy__*`) - When MCPProxy is configured as an MCP server in Claude Code

- 2. **HTTP API** (`curl http://localhost:8080/...`) - For debugging MCPProxy itself

- **This skill is for #1.** For debugging MCPProxy itself, use HTTP API approach sparingly.

- ## FIRST: Detect MCPProxy Connection

- **When user mentions MCPProxy or MCP tools:**

- - "check buildkite mcp"

- - "use slack mcp tools"

- - Any MCPProxy tool request

- **YOU MUST IMMEDIATELY:**

- 1. **Look at your available tools** (passive observation - don't run commands)

- 2. **Scan for tools starting with `mcp__MCPProxy__`**

- **Examples of what you're looking for:**

- ```

- mcp__MCPProxy__retrieve_tools

- mcp__MCPProxy__call_tool

- mcp__MCPProxy__upstream_servers

- ```

- **Decision:**

- - ✅ **See `mcp__MCPProxy__*` tools?** → MCPProxy is connected, use them

- - ❌ **Don't see `mcp__MCPProxy__*` tools?** → MCPProxy MCP server not connected

- **If tools are missing, IMMEDIATELY tell user:**

- > "MCPProxy MCP tools aren't available in this session. The MCPProxy MCP server isn't connected.

- >

- > Try the `/mcp` command and select MCPProxy to reconnect. Once reconnected, you'll have access to the `mcp__MCPProxy__*` tools."

- **DO NOT:**

- - Try bash commands like `claude mcp list` or `mcpproxy list-tools`

- - Try HTTP API with curl

- - Make multiple attempts with different approaches

- - Try to work around the issue

- **Missing `mcp__MCPProxy__*` tools = MCPProxy MCP server not connected = Suggest `/mcp reconnect`. That's it.**

- ## Core Decision Tree (Passive Observation)

- **This is passive observation - look at tools you already have, don't run commands.**

- ```

- Look at your available tools (the tool list in this session)

- ↓

- Do you see ANY tools starting with mcp__MCPProxy__*?

- │

- ├─ YES → MCPProxy is connected

- │ ├─ Discover: mcp__MCPProxy__retrieve_tools

- │ └─ Call: mcp__MCPProxy__call_tool

- │

- └─ NO → MCPProxy MCP server not connected

- └─ Tell user: "Try /mcp command to reconnect"

- ```

- **Key points:**

- - This is OBSERVATION, not execution

- - Don't run `claude mcp list` or any bash command

- - Just scan your available tool list

- - Missing tools = connection issue, not "tools don't exist"

- - Never fall back to HTTP API

- ## When to Use This Skill

- **Use when:**

- - You need to discover what tools MCPProxy exposes

- - You want to call a tool through MCPProxy

- - MCPProxy is configured but you're not sure if MCP tools are available

- - User mentions working with MCP servers or tools

+ MCPProxy is reached two ways: as **MCP tools** (`mcp__MCPProxy__*`) when it's configured as an MCP server in Claude Code, or through its **HTTP API** (`curl http://127.0.0.1:8080/...`). Use the MCP tools. The HTTP API is only for debugging MCPProxy itself.

- **Do NOT use when:**

- - User is asking about non-MCP topics

- - The task doesn't involve MCP tools

+ ## First: is MCPProxy connected?

- ## What You're Looking For

+ Look at the tools you already have, without running anything. MCPProxy is connected if any `mcp__MCPProxy__*` tool appears, either in your tool list or in the deferred-tools list (load deferred ones with ToolSearch before calling them). `mcp__ide__*` and other `mcp__*` prefixes are different servers.

- **When MCPProxy IS connected, your tool list includes:**

- ```

- Available tools:

- - Bash

- - Read

- - Write

- - mcp__MCPProxy__retrieve_tools ← Look for these

- - mcp__MCPProxy__call_tool ← Look for these

- - mcp__MCPProxy__upstream_servers ← Look for these

- - mcp__ide__getDiagnostics

- - mcp__ide__executeCode

- ```

+ If no `mcp__MCPProxy__*` tool appears anywhere, the MCPProxy MCP server isn't connected. Tell the user:

- **When MCPProxy is NOT connected:**

- ```

- Available tools:

- - Bash

- - Read

- - Write

- - mcp__ide__getDiagnostics

- - mcp__ide__executeCode

- ← No mcp__MCPProxy__* tools = Connection issue

- ```

+ > "MCPProxy MCP tools aren't available in this session. Try the `/mcp` command and select MCPProxy to reconnect."

- **Key distinction:**

- - `mcp__ide__*` = Different MCP server (IDE integration)

- - `mcp__MCPProxy__*` = MCPProxy tools for upstream servers

- - Only `mcp__MCPProxy__*` tools indicate MCPProxy connection

+ Then stop. Don't run `claude mcp list` or `mcpproxy`, don't fall back to curl, and don't try workarounds: a running MCPProxy process doesn't mean this session is connected to it, and a string of curl attempts is a sign you're avoiding that answer. MCP tools are function calls, never Bash commands.

## Core Pattern: Discover Then Call

```typescript

// 1. Search for relevant tools

mcp__MCPProxy__retrieve_tools({

query: "keywords describing what you need",

limit: 10

});

// 2. Examine tool schemas in results

// Look at inputSchema to understand parameters

// 3. Call the tool

mcp__MCPProxy__call_tool({

name: "server:tool-name", // From search results

args_json: JSON.stringify({ // MUST be JSON string

param1: "value",

param2: "value"

})

});

```

**Critical:** `args_json` must be a JSON string (use `JSON.stringify()`), not a plain object.

+ Newer MCPProxy versions expose `call_tool_read`, `call_tool_write`, and `call_tool_destructive` instead of a single `call_tool`; use whichever your tool list shows.

## Available MCP Tools

- `mcp__MCPProxy__retrieve_tools` - Search for tools across all upstream servers

- `mcp__MCPProxy__call_tool` - Execute a discovered tool

- `mcp__MCPProxy__upstream_servers` - Manage server configuration

- `mcp__MCPProxy__list_registries` - List available MCP registries

- `mcp__MCPProxy__search_servers` - Find new servers in registries

- `mcp__MCPProxy__read_cache` - Read paginated results

- `mcp__MCPProxy__quarantine_security` - Manage quarantined servers

- ## Quick Reference

- | Task | Check This First | Then Use |

- |------|------------------|----------|

- | Discover tools | Are `mcp__MCPProxy__*` in tool list? | If yes: `retrieve_tools`<br>If no: Suggest `/mcp` |

- | Call a tool | Are `mcp__MCPProxy__*` in tool list? | If yes: `call_tool`<br>If no: Suggest `/mcp` |

- | Debug MCPProxy | N/A | Use HTTP API sparingly |

- ## If MCP Tools Are Missing

- When `mcp__MCPProxy__*` tools are not in your tool list:

- **Tell the user:**

- > "MCPProxy MCP tools aren't available in this session. Try the `/mcp` command and select MCPProxy to reconnect."

- **Do NOT:**

- - Fall back to HTTP API (that's for debugging MCPProxy)

- - Assume the tools don't exist

- - Try bash commands

- - Make multiple curl attempts

- **Reality:** The tools exist when MCP connection is established. Missing tools = connection issue.

- ## Top 3 Common Mistakes

- ### 1. Invoking MCP Tools as Bash Commands

- ```bash

- # ❌ WRONG - MCP tools are not bash commands

- mcp__MCPProxy__retrieve_tools --query "slack tools"

- ```

- ```typescript

- // ✅ CORRECT - Call as MCP tool (function)

- mcp__MCPProxy__retrieve_tools({

- query: "slack tools"

- })

- ```

- **How to tell the difference:**

- - `mcp__server__tool` pattern → MCP tool (function call)

- - `mcpproxy`, `docker` → Bash command (via Bash tool)

- ### 2. Using HTTP API Instead of MCP Tools

- ```bash

- # ❌ WRONG - Don't do this when MCP tools should work

- curl http://127.0.0.1:8080/api/v1/tools?apikey=...

- ```

- ```typescript

- // ✅ CORRECT - Use MCP tools

- mcp__MCPProxy__retrieve_tools({query: "search query"})

- ```

- **HTTP API is only for debugging MCPProxy itself.**

- ### 3. Falling Into the HTTP API Spiral

- ```

- Agent tries: mcp__MCPProxy__call_tool(...)

- Gets error: "No such tool available"

- Agent makes:

- 1. curl attempt with python parsing

- 2. curl attempt with json.tool

- 3. curl attempt with grep

- 4. Python script wrapping curl

- 5. Different parsing strategy...

- ```

- **STOP!** Multiple curl attempts = you're avoiding the real problem: MCP not connected. Suggest `/mcp` instead.

- ## Red Flags - STOP Immediately

- If you think any of these thoughts, **STOP**:

- - "I'll run `mcp__MCPProxy__retrieve_tools` as a bash command"

- - "The `mcp__MCPProxy__*` tools don't exist, I'll use curl"

- - "HTTP API is simpler, I'll use that"

- - "Let me try a different way to parse the HTTP response"

- - "Maybe if I use Python/jq/grep it will work"

- - "The tool error means MCPProxy isn't running"

- **Reality:**

- - `mcp__MCPProxy__*` tools exist when MCP connection is established

- - Missing tools = connection issue, not "tools don't exist"

- - HTTP API is for debugging MCPProxy, not for normal usage

- - Running ≠ Connected. Process can run but MCP not connected.

- ### Red Flags in Error Responses

+ ## Errors that retrying won't fix

When an MCP tool call returns an error, check for these patterns. If matched, **STOP** - retrying won't help.

**Unrecoverable errors - STOP and tell the user:**

| Error Pattern | What It Means | Tell User |

|--------------|---------------|-----------|

| `authentication failed`, `OAuth/token authentication required`, `authorization required` | Upstream server needs re-auth | "Server '{name}' needs re-authentication. Run `mcpproxy auth login --server={name}` or use the MCPProxy system tray to re-authenticate." |

| `is not connected`, `is disabled` | Server offline/disabled | "Server '{name}' isn't connected. Check MCPProxy status with `mcp__MCPProxy__upstream_servers(operation='list')`." |

| `access_denied`, `insufficient_scope` | Missing permissions | "Server '{name}' lacks permissions for this operation. May need to re-authorize with additional scopes." |

**Why retrying won't help:**

These errors require user action outside of Claude:

- Re-running OAuth flow through MCPProxy CLI or system tray

- Fixing server configuration

- Granting additional permissions

**Don't:**

- Retry the same tool with different parameters

- Try other tools on the same server (they'll fail too)

- Fall back to WebFetch/curl (won't have auth either)

## Debugging MCPProxy Connection Issues

If MCPProxy itself isn't working properly (servers won't connect, Docker issues, etc.), you can use these quick checks:

### Quick Health Check

```bash

# 1. Is mcpproxy running?

ps aux | grep mcpproxy | grep -v grep

# 2. Get API key

grep '"api_key"' ~/.mcpproxy/mcp_config.json

# 3. Check server status

curl -s "http://127.0.0.1:8080/api/v1/servers?apikey=YOUR_KEY" | python3 -m json.tool

# 4. Check for recent errors

tail -50 ~/Library/Logs/mcpproxy/main.log | grep -i error

```

**Key status fields to check:**

- `connected`: Boolean - is the server connected?

- `status`: String - current state (connecting, ready, error)

- `last_error`: String - most recent error message

- `tool_count`: Number - how many tools available

### Common MCPProxy Issues

#### "the input device is not a TTY" (Docker servers)

**Fix:** Add `"isolation": {"enabled": false}` to the Docker-based server config.

#### "unexpected argument found" (uvx/npx servers)

**Fix:** Put package name as first arg: `["mcp-server-name", "--arg", "value"]`

#### "Invalid or missing API key" after restart

**Fix:** Check `echo $MCPPROXY_API_KEY` - environment variable overrides config file.

### Restart MCPProxy

```bash

pkill mcpproxy

sleep 2

open /Applications/mcpproxy.app # macOS

# OR

mcpproxy & # Linux/headless

```

- ## Summary

- **The capability:** Use MCPProxy's tool discovery to find and call tools across all upstream MCP servers.

- **The pattern:**

- 1. Check if `mcp__MCPProxy__*` tools exist

- 2. If yes → Use them (discover then call)

- 3. If no → Suggest `/mcp` reconnect

- 4. Never fall back to HTTP API

- **Result:** Fast tool usage with clear error handling.