My Cool Proxy

My Cool Proxy is a Model Context Protocol (MCP) server gateway that tries to solve a lot of perceived problems with MCP as it exists today. In no particular order, those are that:

• Tool descriptions bloat the context window: This is a problem with how most agents integrate with MCP. Rather than implementing abstractions that enable tools to be loaded as needed, most applications dump all MCP tools into the context at once. To mitigate this, My Cool Proxy wraps tools in a Lua interpreter and exposes higher-level tools for discovering tools incrementally. Refer to Progressive Disclosure for more information.
• Tool results bloat the context window, why not use Bash? Rather than using MCP tools, agents could just execute terminal commands and use bash to filter their results - however, this means allowing the agent to perform high-risk actions more frequently. For example, you could allow an agent to use the gh CLI to interact with GitHub, but it can then use the gh CLI to perform mutating or destructive operations, as well. With the GitHub MCP Server, you can instead scope things down to read-only tools trivially. MCP allows you to tightly control what tools agents have access to. To assist with this, My Cool Proxy allows you to further filter the tools exposed to agents.
• Most MCP features are unsupported: Unfortunately, most applications only expose MCP tools to agents, neglecting the other client and server features offered by the protocol. My Cool Proxy aims to be a common abstraction layer for as many protocol features as possible, which allows developers to use the full capabilities of MCP in any MCP-compatible application. This is a work in progress - check the feature support table for more details.
• Managing a config file for multiple agents is a pain: If you use more than a single MCP-compatible application, you'll quickly run into challenges keeping your MCP server configuration synchronized across them. My Cool Proxy solves this by acting as a single integration point for every server you use, reducing the number of servers to keep in sync down to just one.

Quick Start

0. Installation

Install it globally to use it as a CLI tool:

npm install -g @karashiiro/my-cool-proxy

Or run it directly via npx:

npx @karashiiro/my-cool-proxy

1. Configure

The gateway auto-creates a default config on first run. Just run it once to generate the config file:

my-cool-proxy  # Creates config and starts (with no servers)

# Find your config location
my-cool-proxy --config-path

Then edit the config to add your MCP servers.

Example config structure:

{
  "port": 3000,
  "host": "localhost",
  "mcpClients": {
    "my-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

Or, copy the example config for a more complete starting point.

2. Run

# If installed globally
my-cool-proxy

# If running via npx
npx @karashiiro/my-cool-proxy

3. Connect

Add it to your MCP client config in e.g. Claude Desktop:

{
  "mcpServers": {
    "my-cool-proxy": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

4. Use It

Ask your agent to perform a task that your configured MCP servers can help with, and watch it run!

Progressive Disclosure

This proxy acts as a gateway between agents and multiple MCP (Model Context Protocol) servers. Instead of connecting to each MCP server individually, agents connect to this single proxy and gain access to all configured servers through a unified interface.

Agents start with minimal knowledge about what servers or tools are available. They build context progressively:

1. Check the server instructions - My Cool Proxy preloads a small prompt with brief excerpts of the configured servers and tools to prime the agent to use them.
2. Call list-servers - The agent's context now includes names and descriptions of all available MCP servers (e.g., "github", "slack", "database")
3. Call list-server-tools(server_name) - The agent's context expands to include all tool names and descriptions for that specific server
4. Call tool-details(server_name, tool_name) - The agent's context now has complete parameter schemas, return types (if available), and usage examples for a specific tool
5. Call execute(lua_script) - With full context, the agent can write Lua scripts that call the discovered tools

Rather than loading all tools and tool descriptions into the context upfront, this defers loading tools until the agent determines those tools are needed.

Tool Chaining with Lua: Once an agent knows what tools exist, they can compose complex multi-step workflows in a single execute() call, saving the context overhead of any intermediate tool results. The Lua runtime provides access to all discovered servers as globals, with tools callable as async functions.

Sequential tool chaining:

local raw_data = api_server.fetch({ id = 123 }):await()
local processed = processor.transform({ input = raw_data }):await()
result(processed)

Conditional logic:

local status = checker.validate({}):await()
if status.ok then
  result(processor.run({}):await())
else
  result(error_handler.notify({ error = status.message }):await())
end

Iteration with loops:

local results = {}
for i = 1, 5 do
  results[i] = worker.process({ index = i }):await()
end
result({ total = #results, data = results })

Gateway Skills

Gateway Skills are My Cool Proxy's implementation of Agent Skills - reusable context documents that agents can load as MCP Resources. When enabled, agents can:

• Discover skills via an automatically-injected prompt in the gateway's server instructions (or via the _gateway.list_resources() Lua builtin; look for gw-skill:// URIs)
• Read skill content via the _gateway.read_resource() Lua builtin
• Execute skill scripts via the _gateway.invoke_skill_script() Lua builtin

While many agents implement their own skill systems already, these systems are highly fragmented, and it is difficult to reuse the same skills across multiple separate agent applications. While some systems such as skills.sh solve this by copying skills between applications explicitly, My Cool Proxy solves this by centralizing all skills into its own skill management system and exposing them over MCP. To distinguish these from existing skill systems, My Cool Proxy refers to these as "Gateway Skills."

Gateway Skills are disabled by default as they may conflict with existing skill systems built into your agent. See the Configuration Guide for setup options.

For a deeper design discussion about why Gateway Skills are implemented this way, refer to this section in the design docs.

Web Dashboard

My Cool Proxy includes an optional web dashboard for monitoring gateway activity. When enabled, it runs on a separate port and provides:

• Execution history — Browse all Lua script executions with syntax-highlighted scripts and results
• Tool call log — See which MCP tools were called during each execution
• Session monitoring — View active sessions, connected servers, and capabilities
• Real-time updates — New executions stream to the dashboard via WebSocket

Enable it by adding a dashboard section to your config:

{
  "dashboard": {
    "port": 3100,
    "host": "localhost"
  }
}

Then visit http://localhost:3100 in your browser. See the Configuration Guide for details.

Configuration

See the Configuration Guide for the full config reference.

MCP Feature Support Table