How do I use mcp-proxy?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-proxy what can tavily do?" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

mcp-proxy

by shengxiao20

Overview Schema Related Servers Score Discussions

Python

Local

Progressive MCP Server Loading Proxy

Theoretical reference / 理论参考: https://www.anthropic.com/engineering/code-execution-with-mcp

Further write-ups and updates are published on WeChat Official Account VibeStudy — follow for more discussions. 更多介绍与后续更新同步发布在微信公众号 VibeStudy，欢迎关注交流。

English

A stdio MCP server that acts as a proxy in front of other MCP servers, implementing progressive disclosure of tool definitions via a local filesystem cache.

Instead of loading all tool definitions into the model's context upfront, agents discover and load tools on demand — reducing token usage by up to 98%.

Motivation

MCP servers inject their full tool schemas into the model context at session start. Unused tools still consume tokens. When multiple servers are registered, this overhead compounds linearly.

This proxy adds a context-management layer: the agent registers only one server (mcp-proxy), while all real MCP servers are managed under the proxy's config directory. Tool schemas stay out of context until explicitly requested.

How it works

Your prompt
  └── Claude (discovers and calls tools via 5 meta-tools)
        └── mcp-proxy (stdio MCP server)
              └── Real MCP servers (tavily, markitdown, ...)

On startup, the proxy fetches all tool definitions from real MCP servers and writes them to ~/.mcp-proxy/cache/<server>/<tool>.json. At runtime, the agent reads from cache on demand via meta-tools; calls are proxied to the real server for execution.

The cache persists across restarts. Real servers are only contacted on first run or when refresh_cache is called.

Direct mount vs. mcp-proxy:

Direct mount: [session start] → schema permanently occupies context → tokens consumed whether tool is used or not
mcp-proxy: [session start] → only 5 meta-tools → schema fetched on demand → done

Installation

This project uses flat Python modules (no package directory), so you need to tell hatchling which files to ship. The pyproject.toml already includes this configuration.

With uv (recommended)

cd path/to/this/repo
uv venv .venv
uv pip install -e .

uv pip install -e . reads pyproject.toml, registers the current directory as a Python package, and generates a mcp-proxy entry script at .venv/bin/mcp-proxy pointing to the main_sync function in proxy.py. The -e (editable) flag means source files are referenced directly — no reinstall needed after code changes.

The mcp-proxy executable will be at .venv/bin/mcp-proxy.

With pip

pip install -e .

Note: On macOS with Homebrew Python, use pip install -e . --user or use uv instead to avoid PEP 668 errors.

Configuration

1. Create the proxy config

mkdir -p ~/.mcp-proxy

Create ~/.mcp-proxy/config.json and fill in your servers:

{
  "servers": {
    "my-server": {
      "command": "uvx",
      "args": ["my-mcp-server"],
      "env": {
        "API_KEY": "your-key-here"
      }
    }
  }
}

The config format mirrors the MCP server definition format used in Claude Code's settings.json and ~/.claude.json, so you can copy entries directly from there.

Example — proxying Tavily MCP:

{
  "servers": {
    "tavily": {
      "command": "npx",
      "args": ["-y", "tavily-mcp@0.1.2"],
      "env": {
        "TAVILY_API_KEY": "your-tavily-api-key"
      }
    }
  }
}

2. Verify the cache initializes

Run the proxy once to confirm it can reach your configured servers and populate the cache:

.venv/bin/mcp-proxy &
sleep 10
kill %1

You should see output like:

[proxy] Caching tavily...
[proxy] tavily: 2 tools cached

The cache is written to ~/.mcp-proxy/cache/.

3. Register with Claude Code

Add to ~/.claude.json under mcpServers, using the absolute path to the venv executable:

{
  "mcpServers": {
    "mcp-proxy": {
      "command": "/absolute/path/to/repo/.venv/bin/mcp-proxy",
      "args": [],
      "env": {}
    }
  }
}

Note: Use ~/.claude.json, not ~/.claude/settings.json. The latter's mcpServers field is not used for MCP server registration.

Once mcp-proxy is registered in ~/.claude.json, all future MCP servers are added exclusively in ~/.mcp-proxy/config.json — no changes to Claude Code config required.

Configuration files reference

File	Purpose
`~/.mcp-proxy/config.json`	Backend server list (command, args, env). Only file you need to edit when adding new servers.
`~/.mcp-proxy/cache/`	Cached tool definitions, reused across restarts
`~/.claude.json`	Registers `mcp-proxy` itself with Claude Code (one-time setup)

Meta-tools exposed to the agent

Tool	Trigger example	Description
`list_servers`	"What MCP servers do you have?"	List all proxied servers
`list_tools(server)`	"What can tavily do?"	List tool names + short descriptions (low token cost, read from local cache)
`read_tool(server, tool)`	"Show me the full schema for tavily-search"	Read full input schema for a tool
`call_tool(server, tool, args)`	"Search for X using tavily"	Execute a tool
`refresh_cache(server?)`	"Refresh tavily's cache"	Force re-fetch definitions from a server or all servers

Claude Code only has these 5 tool definitions in context. The real schemas for tavily, markitdown, etc. are never in context until you explicitly call read_tool.

Recommended agent workflow

list_servers
  → list_tools("target-server")
    → read_tool("target-server", "specific-tool")   ← required on first use
      → call_tool("target-server", "specific-tool", { ... })

This way only the definitions the agent actually needs enter the context window.

Telling the agent about the workflow

The proxy only exposes 5 meta-tools — the agent has no direct knowledge of the underlying servers or their tools. Add the following to your project's CLAUDE.md or system prompt:

## MCP tool usage

All external tools are accessed through a proxy. Do not assume any tool exists directly.
Follow this workflow whenever you need to use an external tool:

1. Call list_servers to see available servers.
2. Call list_tools(<server>) to browse tool names and short descriptions.
3. Call read_tool(<server>, <tool>) to get the full input schema before calling.
4. Call call_tool(<server>, <tool>, <args>) to execute.

Never skip step 3 — always read the schema before calling a tool you haven't used yet in this session.

Full call trace example — "Search for X using tavily"

Your prompt
│
▼
Claude Code (context only has 5 meta-tools)
│  decides search is needed → selects call_tool
▼
MCP protocol → mcp-proxy process
call_tool({ server: "tavily", tool: "tavily-search", args: { query: "X" } })
│
▼  proxy.py: handle_call_tool()
1. load_config()  ← reads ~/.mcp-proxy/config.json, gets tavily command/args/env
2. connector.call_tool(server_config, "tavily-search", args)
│
▼  connector.py: _open_session()
3. starts subprocess via StdioServerParameters:
   npx -y tavily-mcp@0.1.2  (env injects TAVILY_API_KEY)
4. ClientSession.initialize()  ← MCP handshake
5. session.call_tool("tavily-search", { query: "X" })
│
▼  real tavily-mcp process
6. calls Tavily API (HTTPS)
7. returns result
│
▼  returns via same path
connector → proxy.py → MCP protocol → Claude Code context

Note: Each call to a real MCP server opens an async with session and closes it when done.

Cache structure

~/.mcp-proxy/
  config.json              ← backend server config (only file you need to edit)
  cache/
    servers.json           ← server index + hash
    tavily/
      index.json           ← source for list_tools
      tavily-search.json   ← source for read_tool
      tavily-extract.json
    io.github.microsoft/markitdown/
      index.json
      ...

Currently configured servers (example)

Server	Tool	Purpose
tavily	tavily-search	Web search
tavily	tavily-extract	Extract content from a URL
io.github.microsoft/markitdown	(query with list_tools)	Convert file/URL to Markdown

Key rules

Before calling a tool for the first time, always run read_tool to fetch its schema, then call_tool.
To add a new MCP server, only edit ~/.mcp-proxy/config.json and run refresh_cache — no changes to Claude Code config.
Cache is reused across sessions — no need to re-fetch definitions every time.

To-do / Known limitations

Real MCP servers are connected via async with (open on call, close when done). Per-call connection overhead has not been benchmarked.
HTTP/SSE transport for MCP servers has not been tested yet. The current implementation assumes stdio.
If rewriting as an HTTP server, FastAPI + uvicorn would be a natural fit for replacing the stdio transport.

Related MCP server: mcp-compressor

中文

一个以 stdio MCP 服务器形式运行的代理，位于其他 MCP 服务器的前面，通过本地文件系统缓存实现工具定义的按需加载。

不再将所有工具定义预先加载进模型 context，而是让 agent 按需发现并加载工具 —— 最多可减少 98% 的 token 消耗。

动机

MCP 服务器会在会话开始时将完整的工具 schema 注入模型 context。即使工具未被使用，也会持续占用 token。当注册了多个服务器时，这种开销会随数量线性叠加。

该代理增加了一个 context 管理中间层：agent 只注册一个服务器（mcp-proxy），所有真实的 MCP 服务器都纳入代理的配置目录统一管理。工具 schema 完全不进入 context，只有被显式请求时才注入。

工作原理

你的提示词
  └── Claude（通过 5 个元工具发现和调用工具）
        └── mcp-proxy（stdio MCP 服务器）
              └── 真实 MCP 服务器（tavily、markitdown……）

启动时，代理从真实 MCP 服务器拉取所有工具定义并写入 ~/.mcp-proxy/cache/<server>/<tool>.json。运行时，agent 通过元工具按需从缓存读取；实际调用被代理转发给真实服务器执行。

缓存跨会话持久化。真实服务器仅在首次运行或调用 refresh_cache 时才会被联系。

直接挂载 vs. mcp-proxy：

直接挂载： [会话启动] → schema 永久占位 → 无论是否使用都消耗 token
mcp-proxy： [会话启动] → 仅 5 个元工具 → 按需拉取 schema → 完成

安装

本项目使用扁平 Python 模块（无包目录），需要告知 hatchling 打包哪些文件。pyproject.toml 已包含相关配置。

使用 uv（推荐）

cd path/to/this/repo
uv venv .venv
uv pip install -e .

uv pip install -e . 读取 pyproject.toml，将当前目录注册为 Python 包，并在 .venv/bin/mcp-proxy 生成一个指向 proxy.py 中 main_sync 函数的可执行入口脚本。-e（editable）模式意味着源文件被直接引用，修改代码后无需重新 install。

mcp-proxy 可执行文件位于 .venv/bin/mcp-proxy。

使用 pip

pip install -e .

注意： 在使用 Homebrew Python 的 macOS 上，请使用 pip install -e . --user，或改用 uv，以避免 PEP 668 错误。

配置

1. 创建代理配置

mkdir -p ~/.mcp-proxy

创建 ~/.mcp-proxy/config.json，填入你的服务器：

{
  "servers": {
    "my-server": {
      "command": "uvx",
      "args": ["my-mcp-server"],
      "env": {
        "API_KEY": "your-key-here"
      }
    }
  }
}

配置格式与 Claude Code 的 settings.json 和 ~/.claude.json 中的 MCP 服务器定义格式一致，可直接复制粘贴。

示例 —— 代理 Tavily MCP：

{
  "servers": {
    "tavily": {
      "command": "npx",
      "args": ["-y", "tavily-mcp@0.1.2"],
      "env": {
        "TAVILY_API_KEY": "your-tavily-api-key"
      }
    }
  }
}

2. 验证缓存初始化

运行一次代理，确认它能连接到配置的服务器并填充缓存：

.venv/bin/mcp-proxy &
sleep 10
kill %1

你应该看到类似输出：

[proxy] Caching tavily...
[proxy] tavily: 2 tools cached

缓存写入 ~/.mcp-proxy/cache/。

3. 注册到 Claude Code

在 ~/.claude.json 的 mcpServers 下添加，使用 venv 可执行文件的绝对路径：

{
  "mcpServers": {
    "mcp-proxy": {
      "command": "/absolute/path/to/repo/.venv/bin/mcp-proxy",
      "args": [],
      "env": {}
    }
  }
}

这里的 command 就是 install 后生成的入口脚本，Claude Code 启动时直接执行，项目就以 stdio MCP server 的形式跑起来了。

注意： 使用 ~/.claude.json，而非 ~/.claude/settings.json。后者的 mcpServers 字段不用于 MCP 服务器注册。

mcp-proxy 在 ~/.claude.json 中注册一次后，所有后续 MCP 服务器只需在 ~/.mcp-proxy/config.json 中添加 —— 无需再修改 Claude Code 配置。

配置文件说明

文件	用途
`~/.mcp-proxy/config.json`	后端服务器列表（command、args、env）。添加新服务器时唯一需要编辑的文件。
`~/.mcp-proxy/cache/`	缓存的工具定义，跨会话复用
`~/.claude.json`	将 `mcp-proxy` 本身注册到 Claude Code（一次性配置）

暴露给 Agent 的元工具

工具	触发示例	说明
`list_servers`	"你现在有哪些 MCP 服务器？"	列出所有被代理的服务器
`list_tools(server)`	"tavily 能做什么？"	列出工具名称 + 简短描述（低 token 消耗，从本地缓存读取）
`read_tool(server, tool)`	"告诉我 tavily-search 的完整参数格式"	读取工具完整 JSON Schema
`call_tool(server, tool, args)`	"用 tavily 搜索 XXX"	执行工具
`refresh_cache(server?)`	"刷新 tavily 的缓存"	强制从服务器重新拉取定义

Claude Code 的 context 里只有这 5 个工具的定义。tavily、markitdown 等真实工具的 schema 完全不在 context 里，直到显式调用 read_tool 才会注入。

这正是这个代理节省 token 的核心机制：直接注册 tavily 会一次性把所有工具 schema 注入 context，而 mcp-proxy 方案把真实 schema 挡在 context 门外，按需拉取。

告知 Agent 工作流

代理只暴露 5 个元工具 —— agent 对底层服务器及其工具一无所知。请将以下内容添加到项目的 CLAUDE.md 或系统提示中：

## MCP 工具使用方式

所有外部工具通过代理访问，不要假设任何工具直接存在。
每次需要使用外部工具时，按以下流程操作：

1. 调用 list_servers 查看可用服务器。
2. 调用 list_tools(<server>) 浏览工具名称和简短描述。
3. 调用 read_tool(<server>, <tool>) 获取完整 input schema。
4. 调用 call_tool(<server>, <tool>, <args>) 执行。

不要跳过第 3 步 —— 在本次会话中首次调用某工具前，必须先读取其 schema。

完整调用链路示例 —— "用 tavily 搜索 XXX"

你的提示词
│
▼
Claude Code（context 里只有 5 个元工具）
│  判断需要搜索 → 选择 call_tool
▼
MCP 协议调用 → mcp-proxy 进程
call_tool({ server: "tavily", tool: "tavily-search", args: { query: "XXX" } })
│
▼  proxy.py: handle_call_tool()
1. load_config()  ← 读 ~/.mcp-proxy/config.json，取出 tavily 的 command/args/env
2. connector.call_tool(server_config, "tavily-search", args)
│
▼  connector.py: _open_session()
3. 用 StdioServerParameters 启动子进程：
   npx -y tavily-mcp@0.1.2（env 注入 TAVILY_API_KEY）
4. ClientSession.initialize()  ← MCP 握手
5. session.call_tool("tavily-search", { query: "XXX" })
│
▼  真实 tavily-mcp 进程
6. 调用 Tavily API（HTTPS）
7. 返回结果
│
▼  原路返回
connector → proxy.py → MCP 协议 → Claude Code context

注意： 每次调用真实 MCP 服务器都会以 async with 方式开启会话，用完即关。

缓存文件结构

~/.mcp-proxy/
  config.json              ← 后端服务器配置（唯一需要编辑的文件）
  cache/
    servers.json           ← 服务器索引 + hash
    tavily/
      index.json           ← list_tools 读取源
      tavily-search.json   ← read_tool 读取源
      tavily-extract.json
    io.github.microsoft/markitdown/
      index.json
      ...

当前配置的服务器（示例）

服务器	工具	用途
tavily	tavily-search	网络搜索
tavily	tavily-extract	提取指定 URL 的网页内容
io.github.microsoft/markitdown	(需 list_tools 查询)	文件/URL 转 Markdown

关键规则

首次调用新工具前，必须先 read_tool 获取 schema，再 call_tool。
添加新 MCP 服务器，只需编辑 ~/.mcp-proxy/config.json，然后 refresh_cache，无需改 Claude Code 配置。
缓存跨会话复用，不必每次重新拉取定义。

待办 / 已知限制

真实 MCP 服务器通过 async with 连接（调用时开启，完成后关闭）。单次调用的连接开销尚未做基准测试。
HTTP/SSE 传输方式的 MCP 服务器尚未测试，当前实现假设使用 stdio。
若改写为 HTTP 服务器，可考虑用 FastAPI + uvicorn 替代 stdio 传输层。

Available Tools

5 tools

call_toolB

Execute a tool on a proxied MCP server.

ParametersJSON Schema

Name	Required	Description
`args`	No	Tool arguments (use read_tool to see required fields)
`tool`	Yes
`server`	Yes

TDQS

B3.2/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, and the description does not disclose behavioral traits like side effects, required permissions, rate limits, or error handling. The word 'execute' implies action, but details are lacking for a tool that runs a tool on a server.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that efficiently communicates the tool's purpose without unnecessary words. It is well-structured and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool executes actions on a server, the description lacks essential details like return values, error behavior, and what 'proxied' means. No output schema exists, and parameters are not fully documented, leaving agents with insufficient context for correct usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only 33% of parameters (args) have descriptions in the schema. The description adds minimal value by explaining that args are tool arguments and referencing read_tool for required fields, but server and tool parameters have no descriptions, leaving their purpose partially inferred.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Execute a tool on a proxied MCP server'), identifying the verb-resource relationship. It distinguishes from sibling tools like list_tools (lists tools) and read_tool (reads tool details).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives, such as read_tool for inspecting a tool before execution. The description does not provide any context, prerequisites, or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_serversA

List all proxied MCP servers available in this proxy.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It indicates a read-only list operation but lacks details on potential side effects, rate limits, or response format.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no redundant information, making it highly concise and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list tool with no output schema, the description adequately conveys the action and scope. However, it could optionally mention what information is returned per server to be fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are 0 parameters, and the schema coverage is 100%. Per guidelines, a baseline of 4 is appropriate since no parameter information is needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a clear verb 'List' and specifies the resource 'proxied MCP servers' with the scope 'all...available in this proxy', distinguishing it from sibling tools like call_tool or list_tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for listing servers but does not explicitly state when to use this tool versus alternatives or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_toolsA

List tools available on a server. Returns names and short descriptions only (low token cost). Use read_tool to get the full schema before calling.

ParametersJSON Schema

Name	Required	Description	Default
`server`	Yes	Server name from list_servers

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description reveals that the tool returns only names and short descriptions and emphasizes low token cost, which are useful behavioral traits. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences that front-load the purpose and immediately provide additional guidance. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a straightforward listing tool with one parameter and no output schema, the description covers the action, return value, and next steps adequately.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the parameter description already indicates the server comes from list_servers. The tool description does not add extra meaning beyond that.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the action ('List tools available on a server') and resource, and distinguishes itself from siblings by noting it returns only names and short descriptions with low token cost, directing to read_tool for full schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear context by mentioning low token cost and explicitly advising to use read_tool for full schema, but does not explicitly state when not to use this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

read_toolC

Read the full input schema for a specific tool on a server.

ParametersJSON Schema

Name	Required	Description	Default
`tool`	Yes
`server`	Yes

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden for behavioral traits. It does not disclose whether the operation is read-only, requires authentication, or has side effects. Only the core action is described.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no unnecessary words. However, it is under-specified for the complexity of the tool, balancing conciseness with informativeness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of output schema and parameter descriptions, the description does not fully address the tool's context. It omits what the output looks like, error conditions, and prerequisites, making it incomplete for an agent to reliably use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It merely mentions 'a specific tool on a server,' which maps to the two parameters but provides no additional details like expected formats, constraints, or examples.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Read the full input schema for a specific tool on a server.' This distinguishes it from siblings like list_tools (which lists tools) and call_tool (which invokes a tool).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. The description lacks explicit context or comparisons to sibling tools, leaving the agent to infer usage from the tool name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

refresh_cacheB

Force re-fetch tool definitions from a server (or all servers) and update cache.

ParametersJSON Schema

Name	Required	Description	Default
`server`	No	Server name, or omit to refresh all

TDQS

B3.3/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It only states 'force re-fetch' and 'update cache' but does not disclose potential side effects (e.g., latency, blocking, permission requirements) or whether it is a read-only or mutation operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that conveys the essential action with no wasted words. It is appropriately sized for a simple tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one optional parameter, no output schema), the description covers the main functionality. However, it omits return value (e.g., success/failure indicator) and operational details, making it marginally adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% as the parameter 'server' has a description. The description adds no additional meaning beyond the schema's 'Server name, or omit to refresh all.' Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action: 'Force re-fetch tool definitions from a server (or all servers) and update cache.' It specifies the verb (re-fetch) and the resource (tool definitions, cache), which distinguishes it from sibling tools like list_tools or call_tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, contexts, or situations where refresh_cache is preferred over list_tools or read_tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

5 tool updatesv0.1.0Jul 13, 2026
- First observedcall_tool
- First observedlist_servers
- First observedlist_tools
- First observedread_tool
- First observedrefresh_cache

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.7/5.0

Disambiguation5/5

Each tool has a clear, distinct purpose: listing servers, listing/reading tools, calling tools, and cache refresh. There is no overlap or ambiguity.

Naming Consistency5/5

All tools use snake_case and follow a consistent verb_noun pattern (e.g., call_tool, list_servers). No deviations.

Tool Count4/5

5 tools cover the core proxy functionality. While minimal, it's reasonable for a proxy that relies on downstream servers. Could be expanded slightly for server management.

Completeness4/5

Core operations (listing servers, tools, calling, cache refresh) are present. Missing server add/remove or configuration, but the set is mostly complete for basic use.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

strata
ai.klavis
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Agent Orchestration Autonomous Agents Developer Tools
25,748
mcp-serverOAuth
com.niftypm
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Project Management Communication File Systems
2
Remote MCP A
com.remote-mcp.mcp
The Remote MCP server acts as a standardized bridge between LLM applications (like Claude, ChatGPT, and Cursor) and external services, enabling AI agents to access external tools and resources. Its primary capability is providing a centralized search tool to discover other MCP servers and their respective tools. Unlike local implementations, it runs remotely with OAuth authentication and permission controls for security.
Developer Tools Search Agent Orchestration
13
ToolRouter B
io.github.Humanleap
The OpenRouter for tools. One MCP connection gives any AI agent 254 hosted tools, pay per call.
471

Related MCP Servers

MCP Coordinator
Developer Tools Agent Orchestration
CyberClash
A
license
Not graded
quality
D
maintenance
Acts as a proxy for multiple MCP servers, reducing context window usage from 15,000+ tokens to ~500 tokens by dynamically loading servers on-demand and exposing only 3 tools instead of all tool definitions.
Updated 9 months ago (2025-12-18 06:13 UTC)
5
GPL 3.0
mcp-compressor
Developer Tools AI & Machine Learning
atlassian-labs
A
license
Not graded
quality
A
maintenance
A proxy server that wraps existing MCP servers to significantly reduce token consumption by compressing tool descriptions into a two-step interface. It enables users to integrate extensive toolsets without exceeding context limits or incurring high API costs.
Updated 6 days ago (2026-08-31 19:10 UTC)
116
Apache 2.0
nimble
Developer Tools Agent Orchestration
mquan
A
license
Not graded
quality
D
maintenance
A token-efficient MCP server that reduces context window bloat by lazy loading tool descriptions and proxying calls through three simple tools, with a dashboard for managing connections.
Updated 8 months ago (2026-01-11 17:09 UTC)
21
9
MIT
Modular MCP
Developer Tools Agent Orchestration
d-kimuson
A
license
Not graded
quality
C
maintenance
A proxy MCP server that manages multiple upstream MCP servers by grouping them and loading tool schemas on-demand, reducing LLM context usage.
Updated 10 months ago (2025-11-21 14:23 UTC)
5,883
51
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/shengxiao20/MCP-proxy-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

Progressive MCP Server Loading Proxy

English

Motivation

How it works

Installation

With uv (recommended)

With pip

Configuration

1. Create the proxy config

2. Verify the cache initializes

3. Register with Claude Code

Configuration files reference

Meta-tools exposed to the agent

Recommended agent workflow

Telling the agent about the workflow

Full call trace example — "Search for X using tavily"

Cache structure

Currently configured servers (example)

Key rules

To-do / Known limitations

中文

动机

工作原理

安装

使用 uv（推荐）

使用 pip

配置

1. 创建代理配置

2. 验证缓存初始化

3. 注册到 Claude Code

配置文件说明

暴露给 Agent 的元工具

推荐的 Agent 工作流

告知 Agent 工作流

完整调用链路示例 —— "用 tavily 搜索 XXX"

缓存文件结构

当前配置的服务器（示例）

关键规则

待办 / 已知限制

Available Tools

Tool Schema Changelog

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API