Skip to main content
Glama
cursor-mcp-token-facade

cursor-mcp-token-facade

by rcjavier

cursor-mcp-token-facade

MIT · Cursor-facing MCP facade that keeps token spend low by exposing 5 host tools while proxying an unlimited number of child MCP servers behind a staged catalog.

This is the public, generalized package. It ships typical open examples (filesystem, memory, fetch, …). It does not include private house wiring.

Cursor host (always 5)
  search_tools · invoke_tool · mcp_status · search_resources · read_resource
        │
        ▼
  staged catalog: mode=names (default) | mode=schema | limit
        │
   ┌────┴────┬──────────┬─────────┐
 filesystem memory  fetch*   github*   (* enabled:false until needed)

License (why MIT)

License

Fit for this project

MIT (chosen)

Default for small Node/MCP utilities. Max adoption, trivial for Cursor users to vendor or fork. Matches @modelcontextprotocol/sdk ecosystem norms.

Apache-2.0

Better if you need an explicit patent grant for corporate legal. Use if your org requires it; functionally similar for this size of tool.

GPL / AGPL

Poor fit — scares adoption for editor tooling people copy into private configs.

Recommendation: ship MIT. Keep proprietary child configs (paths, secrets, moat servers) in a private repo; publish only the frozen facade + generic examples.


Related MCP server: MCP-Lens

Why tokens drop (typical model)

Assumptions: ~40 child tools with mid-size JSON schemas; Cursor injects ListTools every turn; agent searches before invoke.

Path

Fat (all schemas on host)

Facade + staged catalog

Δ

Host ListTools / turn

~1 000–3 000+ tok

~100–400 tok (5 slim tools)

often −60% to −90%

Discover 3 tools

full schemas dumped

mode=names ~0.3–0.4× schema mode

~−60% on search

Idle heavy servers

still listed / sometimes spawned

enabled: false → 0 process, 0 schemas

idle tax → 0

Exact savings depend on your children. Rule: never put full child schemas on the host; use search_tools → mode=schema only for the tool you are about to call.


Quick start (behind Cursor)

git clone https://github.com/rcjavier/cursor-mcp-token-facade.git
cd cursor-mcp-token-facade
npm install
mkdir -p "${WORKSPACE_ROOT:-$HOME/workspace}/sandbox"   # filesystem child root
cp examples/profiles/token-light.child-servers.json child-servers.json
# or: cp child-servers.json.example child-servers.json
chmod +x start.sh

Wire one absolute path into the project .cursor/mcp.json:

{
  "mcpServers": {
    "cursor-mcp-token-facade": {
      "command": "/ABSOLUTE/PATH/cursor-mcp-token-facade/start.sh",
      "args": []
    }
  }
}

Disable duplicate marketplace MCP plugins for the same servers you put behind the facade (otherwise Cursor still dumps their tools onto the host).

Reload Cursor MCP.

Agent loop

1. search_tools  { "query": "file", "mode": "names", "limit": 10 }
2. search_tools  { "query": "filesystem__read_file", "mode": "schema", "limit": 1 }
3. invoke_tool   { "tool_name": "filesystem__read_file", "payload": { ... } }

Built-ins always available: echo, calc, plus mcp_status.


Child config (typical examples)

Child

Default

How

filesystem

ON

npx -y @modelcontextprotocol/server-filesystem ${WORKSPACE_ROOT}/sandbox

memory

ON

npx -y @modelcontextprotocol/server-memory

everything

OFF

Official demo kitchen-sink server

fetch

OFF

HTTP fetch MCP

github

OFF

HTTP + Authorization: Bearer ${GITHUB_PAT}

Flip with "enabled": false and reload. Schema: child-servers.schema.json. Live file child-servers.json is gitignored — never commit secrets.

Env expansion: ${WORKSPACE_ROOT}, ${HOME}, ${GITHUB_PAT}, …


Develop

npm test          # staged catalog + token-light profile contracts
npm start         # stdio (what Cursor uses)
MCP_FACADE_MODE=http npm run start:daemon   # optional localhost JSON door :8766

What this is / is not

Is

Is not

Frozen token-law facade + generic examples

Your private stack / moat MCP wiring

Drop-in Cursor stdio server

A replacement for Cursor’s plugin OAuth UX

Safe to open-source under MIT

A dump of machine-specific child-servers.json

Private, opinionated instances should stay private. Publish the pattern; keep the moat local.

Available Tools

5 tools
invoke_toolA

Invoke a built-in or child tool by exact name (serverName__toolName). Discover names via search_tools; child roster via mcp_status.

Inputs: payload (required), tool_name (required).

mcp_statusA

Live status of every child MCP server: name, type, enabled, connected, tool/resource counts, tool names, errors. Use this for roster — not search_tools/invoke_tool descriptions.

Inputs: no named parameters.

read_resourceA

Read one MCP resource by URI from the owning child server.

Inputs: uri (required).

search_resourcesB

Search MCP resources across connected children. Call mcp_status for roster.

Inputs: query (required).

search_toolsA

Search child MCP tools by keyword. Default mode=names (name/description/category only). Use mode=schema for one tool (or tight query) to fetch inputSchema. Optional limit caps hits. Call mcp_status for child server roster.

Inputs: query (required), mode, limit.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool targets a distinct facet of the facade: search_tools (tool discovery), invoke_tool (execution), mcp_status (child server roster), search_resources and read_resource (resource discovery and access). Descriptions actively cross-reference each other to steer agents away from misselection, e.g. 'Use this for roster — not search_tools/invoke_tool descriptions.'

    Naming Consistency4/5

    Four of five names follow a clean verb_noun snake_case pattern (search_tools, invoke_tool, search_resources, read_resource). mcp_status breaks the pattern as a noun phrase, though it is still readable and unambiguous.

    Tool Count5/5

    Five tools is well-suited to a thin facade layer: discovery, invocation, status, and resource read/write-lite operations. Nothing feels redundant or padded, and no core proxy role is left without a tool.

    Completeness4/5

    The set covers tool discovery/invocation, server status, and resource search/read, giving a workable lifecycle for proxying child MCP servers. However, MCP prompts (search_prompts/get_prompt) are absent, and there is no bulk schema listing for tools, which could force repeated single-tool fetches.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Provides per-Subagent MCP controls to any coding agent or client across all your MCPs and prevents context window waste. Loads only 3 tools instead of all your MCP Server's tool definitions. Agents discover tools on-demand, only when needed and only the servers and tools they are allowed.
      4
      117 PyPI
      42
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Acts as a proxy/router for multiple downstream MCP servers, exposing only meta-tools to the host to reduce token usage, enabling efficient search and invocation of tools from a fleet of servers.
      8 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables agents to use many MCP servers without context bloat by exposing meta-tools (search, load, call, run_code) that reduce token usage via progressive disclosure and result trimming.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables agents to search a lightweight catalog, inspect permissions, lazily start trusted MCP servers, and call child tools without keeping all schemas in context. It also loads approved skills on demand and routes third-party additions through a human approval queue.
      1
      103 npm
      1
      MIT