utcp-mcp-gateway

🚀 The Smarter Way to Use MCP — Save 90%+ Tokens with Code Mode

English | 中文

Inspired by Claude Skills’ Progressive Disclosure

claude skills alternative · mcp token optimization · progressive tool discovery · mcp response filtering

---

The Story / 故事

I noticed Claude Skills works amazingly well — Claude dynamically discovers and loads only the skills it needs, avoiding context overload.

But most agent frameworks? They dump 500+ tool definitions into the context at once. And MCP responses? Often 10,000+ chars of raw data that waste your tokens.

Then I discovered UTCP — exactly what I needed! Progressive tool discovery built-in. And Cloudflare’s Code Mode? One code block executes everything. Brilliant!

So I built on top of UTCP: Progressive Discovery + Code Mode + LLM Filtering — the smarter way to use MCP.

The best part? Just add one config block. Works with Claude Desktop, Windsurf, Cursor, Dify, and any MCP-compatible client. No extra servers needed.

Looking for…?

• ✅ Claude Skills alternative for your MCP setup
• ✅ Better MCP tool management without context overload
• ✅ Progressive tool discovery — load tools on demand
• ✅ OpenAPI/Swagger to tools — register REST APIs as tools
• ✅ MCP token optimization — reduce 90%+ token waste
• ✅ MCP response filtering — smart summarization

You’re in the right place.

What is this?

LLMs are great at writing code, but terrible at tool calling.

Traditional MCP exposes tools directly to LLMs — but LLMs struggle with:

• Too many tools (500+ definitions = confusion)
• Huge responses (10,000+ chars = wasted tokens)
• Multiple round trips (15+ API calls = slow & expensive)

utcp-mcp-gateway fixes all of this:

Traditional:  User → LLM → Tool1 → LLM → Tool2 → LLM → Tool3 → Result
              (15+ calls, $26/day, slow)

Code Mode:    User → LLM writes code → Execute all at once → Result  
              (1 call, $0.87/day, fast)

Result: $9,536/year savings (benchmark source)

Features

Quick Start

Zero config files needed! Just add to Claude Desktop config:

Mode 1: HTTP MCP (Remote)

{
  "mcpServers": {
    "gateway": {
      "command": "npx",
      "args": ["-y", "utcp-mcp-gateway"],
      "env": {
        "MCP_URL": "https://mcp.context7.com/mcp",
        "MCP_NAME": "context7",
        "LLM_API_KEY": "sk-xxx",
        "LLM_BASE_URL": "https://api.openai.com/v1",
        "LLM_MODEL": "gpt-4o-mini"
      }
    }
  }
}

Mode 2: stdio MCP (Local)

{
  "mcpServers": {
    "gateway": {
      "command": "npx",
      "args": ["-y", "utcp-mcp-gateway"],
      "env": {
        "MCP_COMMAND": "npx",
        "MCP_ARGS": "-y,@anthropic/mcp-server-filesystem",
        "MCP_NAME": "filesystem",
        "MCP_TRANSPORT": "stdio",
        "LLM_API_KEY": "sk-xxx"
      }
    }
  }
}

⚠️ Windows Users: Use cmd /c npx instead of npx:

"command": "cmd",
"args": ["/c", "npx", "-y", "utcp-mcp-gateway"]

Environment Variables

That’s it! Restart Claude Desktop and try: “Search for React useState examples”

How It Works

┌──────────────┐     ┌─────────────────────────────────┐     ┌─────────────┐
│   Your AI    │────▶│      utcp-mcp-gateway           │────▶│ Any MCP     │
│ (Claude etc) │     │  ┌─────────┐  ┌─────────────┐   │     │ (Context7)  │
└──────────────┘     │  │  UTCP   │  │ LLM Filter  │   │     └─────────────┘
                     │  │ search  │  │ 10K→300char │   │
                     │  └─────────┘  └─────────────┘   │
                     └─────────────────────────────────┘

Gateway exposes 4 tools to your AI:

Context-Aware Summarization

When using call_tool_chain with filter_response: true, you can provide a purpose parameter to guide the LLM summarization:

call_tool_chain({
  code: "const docs = await context7.context7_get_library_docs({...}); return docs;",
  filter_response: true,
  purpose: "Find React useState usage examples"
})

The LLM will extract only information relevant to your purpose, instead of generic summarization.

Example Flow

User: "How do I use React useState?"

1. AI calls search_tools("react")        → Returns tools with TypeScript interfaces
2. AI calls call_tool_chain with code:
   const id = await context7.context7_resolve_library_id({ libraryName: "react" });
   const docs = await context7.context7_get_library_docs({ libraryId: id, topic: "useState" });
   return docs;
3. Gateway executes code and returns result
4. AI receives structured response

Token Savings Benchmarks

Configuration

Single MCP

MCP_URL=https://mcp.context7.com/mcp
MCP_NAME=context7

Multiple MCPs (Recommended: Numbered Style)

Use numbered environment variables for clear configuration:

{
  "mcpServers": {
    "gateway": {
      "command": "npx",
      "args": ["-y", "utcp-mcp-gateway"],
      "env": {
        "MCP_1_NAME": "context7",
        "MCP_1_URL": "https://mcp.context7.com/mcp",
        
        "MCP_2_NAME": "filesystem",
        "MCP_2_COMMAND": "npx",
        "MCP_2_ARGS": "-y,@anthropic/mcp-server-filesystem,/path/to/dir",
        
        "LLM_API_KEY": "sk-xxx",
        "MAX_RESPONSE_CHARS": "10000"
      }
    }
  }
}

Numbered variables:

• MCP_1_NAME, MCP_1_URL - First MCP (HTTP mode)
• MCP_2_NAME, MCP_2_COMMAND, MCP_2_ARGS - Second MCP (stdio mode)
• Up to MCP_20_* supported

Multiple MCPs (Alternative: Semicolon Style)

{
  "env": {
    "MCP_URL": "https://mcp.context7.com/mcp;https://mcp.deepwiki.com/mcp",
    "MCP_NAME": "context7;deepwiki"
  }
}

LLM Settings

Smart Router Settings (v0.1.20+)

How it works:

• list_tools returns brief summaries instead of full schemas (saves tokens)
• search_tools uses LLM to understand intent and recommend relevant tools (uses full descriptions for accuracy)
• Falls back to keyword search if LLM is unavailable
• Fuzzy matching for tool names in case LLM returns slightly different names
• Pre-truncates large responses (>200k chars) before LLM summarization

OpenAPI Settings (v0.1.24+)

Register REST APIs directly from OpenAPI/Swagger specs:

# Example: APIs.guru (public API directory)
OPENAPI_1_NAME=apisguru
OPENAPI_1_URL=https://api.apis.guru/v2/openapi.yaml

# Example with authentication
OPENAPI_2_NAME=my_api
OPENAPI_2_URL=https://api.example.com/openapi.json
OPENAPI_2_AUTH_TYPE=api-key
OPENAPI_2_AUTH_TOKEN=sk-xxx
OPENAPI_2_AUTH_VAR=X-Api-Key
OPENAPI_2_AUTH_LOCATION=header

How it works:

• Downloads and parses OpenAPI 2.0/3.0 specifications
• Converts each operation to a UTCP tool
• Tool name = operationId from OpenAPI spec
• Tool description = summary or description from OpenAPI spec
• Supports API Key, Bearer, Basic, and OAuth2 authentication

Requirements:

• Each API operation must have an operationId (operations without it are skipped)
• File upload parameters (type: file) are not supported by UTCP SDK

---

故事

我发现 Claude Skills 效果惊人 — Claude 动态发现并只加载需要的技能，避免上下文过载。

但大多数 Agent 框架？一次性把 500+ 工具定义塞进上下文。而且 MCP 响应？经常是 10,000+ 字符的原始数据，白白浪费 Token。

然后我惊喜地发现了 UTCP — 正是我需要的！内置渐进式工具发现。还有 Cloudflare 的 Code Mode？一段代码执行全部。太妙了！

于是我在 UTCP 基础上做了这个：渐进式发现 + Code Mode + LLM 过滤 — 更聪明的 MCP 使用方式。

最棒的是？只需加一段配置。兼容 Claude Desktop、Windsurf、Cursor、Dify 等所有 MCP 客户端。无需额外服务器。

你在找…？

• ✅ Claude Skills 替代方案 — 用于你的 MCP 配置
• ✅ 更好的 MCP 工具管理 — 无上下文过载
• ✅ 渐进式工具发现 — 按需加载工具
• ✅ OpenAPI 转工具 — 直接从 OpenAPI/Swagger 注册 REST API
• ✅ MCP Token 优化 — 减少 90%+ Token 浪费
• ✅ MCP 响应过滤 — 智能摘要

你来对地方了。

这是什么？

LLM 擅长写代码，但不擅长调用工具。

传统 MCP 直接把工具暴露给 LLM — 但 LLM 面临：

• 工具太多（500+ 定义 = 困惑）
• 响应太大（10,000+ 字符 = 浪费 Token）
• 往返太多（15+ 次 API 调用 = 慢且贵）

utcp-mcp-gateway 一次解决所有问题：

传统方式:   用户 → LLM → 工具1 → LLM → 工具2 → LLM → 工具3 → 结果
            (15+ 次调用, $26/天, 慢)

Code Mode:  用户 → LLM 写代码 → 一次执行全部 → 结果
            (1 次调用, $0.87/天, 快)

结果：每年节省 $9,536 (基准测试来源)

核心功能

快速开始

零配置文件！ 直接添加到 Claude Desktop 配置：

模式 1：HTTP MCP（远程）

{
  "mcpServers": {
    "gateway": {
      "command": "npx",
      "args": ["-y", "utcp-mcp-gateway"],
      "env": {
        "MCP_URL": "https://mcp.context7.com/mcp",
        "MCP_NAME": "context7",
        "LLM_API_KEY": "sk-xxx",
        "LLM_BASE_URL": "https://api.openai.com/v1",
        "LLM_MODEL": "gpt-4o-mini"
      }
    }
  }
}

模式 2：stdio MCP（本地）

{
  "mcpServers": {
    "gateway": {
      "command": "npx",
      "args": ["-y", "utcp-mcp-gateway"],
      "env": {
        "MCP_COMMAND": "npx",
        "MCP_ARGS": "-y,@anthropic/mcp-server-filesystem",
        "MCP_NAME": "filesystem",
        "MCP_TRANSPORT": "stdio",
        "LLM_API_KEY": "sk-xxx"
      }
    }
  }
}

⚠️ Windows 用户： 使用 cmd /c npx 代替 npx：

"command": "cmd",
"args": ["/c", "npx", "-y", "utcp-mcp-gateway"]

环境变量

配置好后重启 Claude Desktop，试试：“搜索 React useState 用法”

工作原理

┌──────────────┐     ┌─────────────────────────────────┐     ┌─────────────┐
│   你的 AI    │────▶│      utcp-mcp-gateway           │────▶│  任意 MCP   │
│ (Claude 等)  │     │  ┌─────────┐  ┌─────────────┐   │     │ (Context7)  │
└──────────────┘     │  │  UTCP   │  │ LLM 过滤器  │   │     └─────────────┘
                     │  │  搜索   │  │ 10K→300字符 │   │
                     │  └─────────┘  └─────────────┘   │
                     └─────────────────────────────────┘

Gateway 向你的 AI 暴露 4 个工具：

上下文感知摘要

使用 call_tool_chain 时，设置 filter_response: true 并提供 purpose 参数，LLM 会根据你的目的智能提取相关信息：

call_tool_chain({
  code: "const docs = await context7.context7_get_library_docs({...}); return docs;",
  filter_response: true,
  purpose: "查找 React useState 的用法示例"
})

LLM 会只提取与你目的相关的信息，而不是泛泛的摘要。

调用流程示例

用户: "React useState 怎么用？"

1. AI 调用 search_tools("react")        → 返回带 TypeScript 接口的工具
2. AI 调用 call_tool_chain 执行代码：
   const id = await context7.context7_resolve_library_id({ libraryName: "react" });
   const docs = await context7.context7_get_library_docs({ libraryId: id, topic: "useState" });
   return docs;
3. Gateway 执行代码并返回结果
4. AI 收到结构化响应

Token 节省实测

配置说明

单个 MCP

MCP_URL=https://mcp.context7.com/mcp
MCP_NAME=context7

多个 MCP（推荐：编号方式）

使用编号环境变量进行清晰配置：

{
  "mcpServers": {
    "gateway": {
      "command": "npx",
      "args": ["-y", "utcp-mcp-gateway"],
      "env": {
        "MCP_1_NAME": "context7",
        "MCP_1_URL": "https://mcp.context7.com/mcp",
        
        "MCP_2_NAME": "filesystem",
        "MCP_2_COMMAND": "npx",
        "MCP_2_ARGS": "-y,@anthropic/mcp-server-filesystem,/path/to/dir",
        
        "LLM_API_KEY": "sk-xxx",
        "MAX_RESPONSE_CHARS": "10000"
      }
    }
  }
}

编号变量：

• MCP_1_NAME, MCP_1_URL - 第一个 MCP（HTTP 模式）
• MCP_2_NAME, MCP_2_COMMAND, MCP_2_ARGS - 第二个 MCP（stdio 模式）
• 最多支持 MCP_20_*

多个 MCP（备选：分号方式）

{
  "env": {
    "MCP_URL": "https://mcp.context7.com/mcp;https://mcp.deepwiki.com/mcp",
    "MCP_NAME": "context7;deepwiki"
  }
}

LLM 配置

智能路由配置 (v0.1.20+)

工作原理：

• list_tools 返回精简摘要而非完整 schema（节省 token）
• search_tools 使用 LLM 理解意图并推荐相关工具（使用全量描述确保准确性）
• LLM 不可用时回退到关键词搜索
• 工具名模糊匹配，容错 LLM 返回格式不完全一致的情况
• 超大响应（>200k 字符）预截断后再进行 LLM 摘要

OpenAPI 配置 (v0.1.24+)

直接从 OpenAPI/Swagger 规范注册 REST API：

# 示例：APIs.guru（公开的 API 目录）
OPENAPI_1_NAME=apisguru
OPENAPI_1_URL=https://api.apis.guru/v2/openapi.yaml

# 带认证的示例
OPENAPI_2_NAME=my_api
OPENAPI_2_URL=https://api.example.com/openapi.json
OPENAPI_2_AUTH_TYPE=api-key
OPENAPI_2_AUTH_TOKEN=sk-xxx
OPENAPI_2_AUTH_VAR=X-Api-Key
OPENAPI_2_AUTH_LOCATION=header

工作原理：

• 下载并解析 OpenAPI 2.0/3.0 规范
• 每个操作转换为一个 UTCP 工具
• 工具名 = OpenAPI 规范中的 operationId
• 工具描述 = OpenAPI 规范中的 summary 或 description
• 支持 API Key、Bearer、Basic 和 OAuth2 认证

注意事项：

• API 操作必须有 operationId（没有的会被跳过）
• 文件上传参数（type: file）不被 UTCP SDK 支持

---

Credits / 致谢

This project is built on top of amazing open-source work:

• UTCP (Universal Tool Calling Protocol) - The protocol that makes this possible
• @utcp/code-mode - Code execution capabilities
• @utcp/sdk - UTCP SDK
• @modelcontextprotocol/sdk - MCP SDK by Anthropic

License

MIT © 2025 reinn