MCP Client

A universal client for connecting to MCP (Model Context Protocol) servers. This skill provides a reusable script that any other skill can bundle to access MCP servers dynamically.

Why Use This?

Instead of loading all MCP tool definitions into context (which bloats tokens), this pattern:

1. Discovers tools on-demand - only load what you need
2. Caches schemas - emit to references/ for progressive disclosure
3. Processes data locally - results flow through script, not context
4. Saves 80-98% tokens - per Anthropic's code execution research

Quick Start

1. Copy the script to your skill

cp scripts/mcp-client.py /path/to/your-skill/scripts/

2. Discover available tools

# HTTP transport
python scripts/mcp-client.py list --url http://localhost:8080

# stdio transport (local server)
python scripts/mcp-client.py list --stdio "npx -y @modelcontextprotocol/server-github"

3. Cache tool schemas (one-time setup)

python scripts/mcp-client.py emit --url http://localhost:8080 > references/tools.md

4. Call tools at runtime

python scripts/mcp-client.py call \
  --url http://localhost:8080 \
  --tool create_issue \
  --params '{"title": "Bug", "body": "Description"}'

Commands

Transport Options

Examples

Connect to GitHub MCP server

# Using stdio (local)
python scripts/mcp-client.py list \
  --stdio "npx -y @modelcontextprotocol/server-github"

# Using HTTP (remote)
python scripts/mcp-client.py list \
  --url https://mcp.example.com/github \
  --header "Authorization: Bearer $TOKEN"

Call a tool with complex parameters

python scripts/mcp-client.py call \
  --url http://localhost:8080 \
  --tool search_issues \
  --params '{
    "query": "is:open label:bug",
    "limit": 10,
    "sort": "updated"
  }'

Emit cached documentation

# Markdown (for references/)
python scripts/mcp-client.py emit --url http://localhost:8080 --format markdown

# JSON (for programmatic use)
python scripts/mcp-client.py emit --url http://localhost:8080 --format json

Creating a Domain Skill with MCP

Here's how to create a new skill that uses an MCP server:

1. Create skill structure

my-domain-skill/
├── SKILL.md
├── scripts/
│   └── mcp-client.py    # Copy from this skill
└── references/
    └── tools.md         # Generated by emit

2. Write your SKILL.md

---
name: my-domain-skill
description: Does X using the Y MCP server
allowed-tools: Bash(python:*) Read
---

# My Domain Skill

## Setup
Ensure MCP server is running at http://localhost:8080

## Available Tools
See [references/tools.md](references/tools.md)

## Workflows

### Do something useful
1. List available items: `python scripts/mcp-client.py call --url ... --tool list_items`
2. Process results...

3. Generate cached tool documentation

cd my-domain-skill
python scripts/mcp-client.py emit --url http://localhost:8080 > references/tools.md

Now agents can read references/tools.md on-demand instead of loading all tool definitions upfront.

Architecture

┌─────────────────────────────────────────────────────────────┐
│ Agent reads SKILL.md (~100 tokens)                          │
│ Agent reads references/tools.md on-demand (if needed)       │
│ Agent runs: python scripts/mcp-client.py call ...           │
│ → Data flows through script, NOT context window             │
└─────────────────────────────────────────────────────────────┘
                              ↓
              ┌───────────────────────────────┐
              │   scripts/mcp-client.py       │
              │   ────────────────────────    │
              │   HTTP or stdio transport     │
              │   JSON-RPC over MCP protocol  │
              └───────────────────────────────┘
                              ↓
              ┌───────────────────────────────┐
              │      Any MCP Server           │
              │   (GitHub, Slack, custom...)  │
              └───────────────────────────────┘

Reference

See [references/mcp-protocol.md](references/mcp-protocol.md) for protocol details.