---
title: MCP Progressive Disclosure - Protocol Extension
emoji: 🚀
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: 6.0.0
app_file: app.py
pinned: false
tags:
  - building-mcp-track-enterprise
  - building-mcp-track-customer
  - building-mcp-track-creative
---

# MCP Progressive Disclosure 🚀

**Track 1: Building MCP - Protocol Extension**  
**MCP 1st Birthday Hackathon Submission**

📺 **Social Post & Demo Video: https://x.com/AppRushAI/status/1995274123279536330**

---

## 🎯 The Problem

Standard MCP servers send **ALL tool descriptions** to the LLM at connection time. For enterprise servers with 50-100+ tools (AWS, Jira, Kubernetes, Salesforce), this results in:

- **30,000-50,000 tokens** loaded before the user even asks a question
- Wasted context window space on tools that may never be used
- Reduced space for actual conversation and reasoning
- Poor scalability as servers add more tools

**Example:** An AWS MCP server with 100 tools × 400 tokens each = **40,000 tokens** of pure overhead.

---

## 💡 The Solution: Progressive Disclosure

We've created a **protocol extension** for MCP that implements lazy-loading of tool descriptions through a two-stage discovery process:

### Stage 1: Selection (Minimal Descriptions)
Server sends ultra-minimal 1-sentence descriptions via `tools/list`:
```json
{
  "name": "aws_ec2_launch_instance",
  "description": "Launches a new AWS EC2 instance with specified configuration.",
  "inputSchema": {"type": "object", "properties": {}}
}
```

### Stage 2: Usage (Full Descriptions On-Demand)
Agent fetches full descriptions only when needed via `tool_descriptions` resource:
```
resource:///tool_descriptions?tools=aws_ec2_launch_instance
```

Returns complete schema, examples, error handling, and **authorizes the tool for the session**.

### Result: 80-90% Token Reduction
- **Standard Mode:** 40,000 tokens loaded upfront
- **Progressive Mode:** ~500 tokens initial + ~400 per tool fetched = **~1,700 tokens** for 3 tools used
- **Savings:** 96% reduction in typical workflows!

---

## 🎬 Live Demo

This Space lets you experience the difference:

1. **Choose Mode:** Standard (load all) vs. Progressive (lazy load)
2. **Start Server:** Click "Start/Restart Server"
3. **Observe Metrics:** Watch the "Initial Token Load" difference
4. **Ask Questions:** Try queries like "What time is it?" or "Deploy a Kubernetes pod"
5. **Compare Logs:**
   - **Standard:** Immediate tool execution
   - **Progressive:** Fetches description → Executes tool

### Sample Queries (Try These!)
- "What time is it?"
- "Calculate 125 multiplied by 8"
- "Generate a random number between 1 and 100"
- "Reverse the string 'hackathon'"
- "Encode 'Hello World' to base64"

**Note:** Complex enterprise tools (AWS, Kubernetes, Jira, etc.) are simulation placeholders that demonstrate how the protocol handles verbose tool descriptions with realistic token counts.

---

## 📚 Protocol Documentation

The full specification is available in this repository:
- **[Protocol Spec v2.0](docs/spec_mcp_progressive_disclosure_v2_0.md)** - Complete protocol definition
- **[Implementation Guide](docs/guide_progressive_disclosure_implementation.md)** - Practical implementation advice

### Key Features
✅ **Standards-Compliant:** Uses only standard MCP primitives (no new protocol methods)  
✅ **Session-Based Auth:** Ensures descriptions are fetched before tool use  
✅ **Backward Compatible:** Servers remain fully MCP-compliant  
✅ **Production-Ready:** Includes error handling, security considerations, and best practices

---

## 🛠️ Technical Implementation

### Server-Side
- Dual-mode MCP server (Standard vs. Progressive)
- 20 tools: 9 working (time, math, encoding) + 11 enterprise simulations (AWS, K8s, Jira)
- Session-based authorization tracking
- Resource endpoint for lazy-loading tool descriptions

### Client-Side
- OpenAI GPT-4o agent with tool calling
- Real-time token counting and metrics
- Progressive disclosure workflow detection and enforcement
- Gradio 6 UI for interactive comparison

### Architecture
```
User Query → Agent (with system prompt) → MCP Client
                ↓
         [Progressive Mode]
    1. List tools (minimal)
    2. Select tool
    3. Fetch full description via resource
    4. Authorize tool
    5. Execute tool
```

---

## 🎯 Real-World Impact

This extension enables:
- **Enterprise MCP Servers** with 100+ tools without context bloat
- **Multi-Domain Assistants** that only load relevant tool details
- **Cost Optimization** by reducing input tokens per request
- **Better Context Utilization** leaving more room for reasoning and conversation

### Use Cases
- AWS/Cloud infrastructure management (50-100 tools)
- Enterprise SaaS integrations (Salesforce, Jira, Slack, etc.)
- Developer tooling (Git, CI/CD, monitoring)
- Multi-domain knowledge systems

---

## 📊 Demo Tools Included

**Fully Working Tools (9):**
- `get_current_time` - Returns current server time
- `calculate` - Performs arithmetic operations
- `generate_random` - Generates random numbers
- `echo_text`, `reverse_string` - Text manipulation
- `base64_encode`, `base64_decode` - Encoding utilities
- `count_words`, `convert_units` - Analysis and conversion

**Enterprise Tool Simulations (11):**
These tools have realistic, verbose descriptions (400+ tokens each) to demonstrate token savings, but return simulation responses:
- `aws_ec2_launch_instance`, `aws_s3_create_bucket`
- `db_postgres_query`, `db_mongo_find`
- `jira_create_issue`, `github_create_pull_request`
- `slack_send_message`, `stripe_create_charge`
- `k8s_deploy_pod`, `salesforce_update_lead`
- `datadog_query_metrics`

**Purpose:** The combination of working + simulated tools shows how Progressive Disclosure scales to enterprise scenarios with 50-100+ tools.

---

## 🏆 Hackathon Submission

**Track:** Track 1 - Building MCP (Protocol Extension)  
**Category:** Protocol Extension / Optimization  
**Author:** Michael Martin  
**Social Post:** https://x.com/AppRushAI/status/1995274123279536330

---

## 🚀 Getting Started Locally

```bash
# Install dependencies
pip install -r requirements.txt

# Set your OpenAI API key
export OPENAI_API_KEY=sk-your-key-here

# Run the demo
python3 app.py
```

---

## 📝 License

MIT License - See LICENSE file for details.

---

## 🙏 Acknowledgments

Built for the **MCP 1st Birthday Hackathon** hosted by Anthropic and Gradio on Hugging Face.

Special thanks to the MCP community for feedback and the Anthropic team for creating the Model Context Protocol.