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:

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

Quick Start

1. Copy the script to your skill

bash

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

2. Discover available tools

bash

# 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)

bash

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

4. Call tools at runtime

bash

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

Commands

Command	Description
`list`	List available tools (use `-v` for full details)
`call`	Call a tool with parameters
`emit`	Generate documentation (`--format markdown\|json`)
`resources`	List available resources
`prompts`	List available prompts

Transport Options

Option	Description
`--url`, `-u`	HTTP URL of MCP server
`--stdio`, `-s`	Command to start stdio MCP server
`--header`, `-H`	HTTP header (can repeat)

Examples

Connect to GitHub MCP server

bash

# 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

bash

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

bash

# 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

code

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

2. Write your SKILL.md

yaml

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

bash

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

code

┌─────────────────────────────────────────────────────────────┐
│ 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 for protocol details.