Provides a proxied GitHub MCP integration, disabled by default, that authenticates with a GitHub PAT via Authorization header to enable GitHub-related tools behind the facade.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@cursor-mcp-token-facade search tools for filesystem, then read sandbox/hello.txt"
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.
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 | Fit for this project |
MIT (chosen) | Default for small Node/MCP utilities. Max adoption, trivial for Cursor users to vendor or fork. Matches |
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
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 |
| ~−60% on search |
Idle heavy servers | still listed / sometimes spawned |
| 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.
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.shWire 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.
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 | Default | How |
| ON |
|
| ON |
|
| OFF | Official demo kitchen-sink server |
| OFF | HTTP fetch MCP |
| OFF | HTTP + |
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}, …
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 :8766Is | 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 |
Private, opinionated instances should stay private. Publish the pattern; keep the moat local.
Invoke a built-in or child tool by exact name (serverName__toolName). Discover names via search_tools; child roster via mcp_status.
| Name | Required | Description | Default |
|---|---|---|---|
| payload | Yes | JSON arguments for the target tool | |
| tool_name | Yes | Exact name from search_tools (e.g. 'echo' or 'filesystem__read_file') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden, and it does disclose the addressing scheme and the discovery path. However, it says nothing about the invocation mechanics that matter here: that the payload is forwarded verbatim, that the target tool's errors/behavior are surfaced, or that this proxy can trigger destructive operations on the target. The disclosure is useful but thin for a generic dispatch tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the core action and followed by the discovery dependency. No filler, and the most important information (exact name format) comes first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a generic dispatch tool with no annotations and no output schema, the definition covers purpose and name acquisition but omits how results come back and how target failures propagate. It is callable, but an agent lacks the runtime expectations this kind of tool warrants.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters are already fully documented in the schema, including the exact-name format and payload semantics. The description's naming-format clause largely restates the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Invoke') and resource ('built-in or child tool by exact name'), and the '(serverName__toolName)' clause pins down the addressing model. It is clearly separable from its siblings: search_tools discovers names and mcp_status enumerates children, while this one executes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It routes the agent to the right prerequisite tools ('Discover names via search_tools; child roster via mcp_status'), which tells the agent what to do first. It stops short of stating exclusions or when a direct/sibling call is preferable, so it gives clear context but not full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden and does reasonably well: 'Live status' signals a dynamic read, and the enumerated fields include 'errors', telling the agent it can surface per-server failures. It does not say whether the call is read-only, whether it probes servers actively, or what happens when a child server is unreachable beyond the 'errors' field.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the resource and its return contents, then the routing guidance. The field enumeration is dense but each item earns its place by telling the agent what it gets back in the absence of an output schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Because there is no output schema, the description compensates by listing the returned fields, and with zero parameters there is nothing else to cover on the input side. Minor gaps remain: no note on permissions, latency, or whether 'Live' means an active probe of each child server.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there are no parameter semantics to document; the 4 baseline applies. The description correctly avoids inventing filtering options that the empty schema does not support.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource ('Live status of every child MCP server') and enumerates the exact fields returned (name, type, enabled, connected, tool/resource counts, tool names, errors). It also distinguishes itself from the sibling tools by name, so an agent can tell it apart from search_tools/invoke_tool without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly routes usage ('Use this for roster') and names the tools it is not for (search_tools/invoke_tool descriptions). The exclusion is a little terse — it doesn't spell out the selecting condition beyond 'roster' — but the when/when-not framing is clear enough to guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one MCP resource by URI from the owning child server.
| Name | Required | Description | Default |
|---|---|---|---|
| uri | Yes | Exact URI from search_resources |
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 implies a non-mutating single-resource fetch and clarifies routing to the owning child server, but says nothing about error behavior when the URI is unknown, permission requirements, or what is returned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with a clear verb-resource-scope structure and zero filler; every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read tool with no output schema, the description is adequate on mechanics but does not state what a successful read yields or how failures surface, leaving the agent to infer the response shape.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the 'uri' parameter and its provenance are already documented in the schema; the description adds only the 'owning child server' routing nuance and no format details. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (read) and resource (one MCP resource) plus the key scoping detail that it is addressed by URI from the owning child server. It is clearly distinct from search_resources, though it does not name the sibling explicitly in the description itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: the schema notes the URI must come from search_resources, which suggests a search-then-read workflow, but the description gives no explicit when-to-use, prerequisites, or when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search MCP resources across connected children. Call mcp_status for roster.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search keyword |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden, yet it discloses nothing about read-only behavior, result limits, pagination, or what happens when no children match. It adds only the roster pointer.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with the action front-loaded and the prerequisite hint trailing. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter search tool this is close to adequate, but with no annotations and no output schema, the description leaves the agent guessing about result shape and whether results span all children or must be scoped.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single query parameter, so the baseline is 3. The description adds no query syntax, matching semantics, or formatting beyond what the schema already documents.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Search) and resource (MCP resources) plus scope (across connected children), which distinguishes it from siblings like search_tools and read_resource. It does not explicitly name a sibling it is not, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The pointer to mcp_status for the roster implies a discovery prerequisite but does not state when to use this tool versus search_tools or read_resource. Usage is implied rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | names (default) = compact; schema = include inputSchema | |
| limit | No | Max hits (default 20) | |
| query | Yes | Keyword (e.g. 'file', 'memory', 'github', 'fetch') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It does disclose mode semantics, that names mode returns name/description/category only, and that limit caps hits, but says nothing about read-only nature, whether the search spans all child servers, or truncation/ordering behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four dense sentences, zero waste, with the core purpose front-loaded and the default mode stated immediately after. Every sentence adds actionable detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description responsibly describes what each mode returns. It covers mode selection, result shape, and the roster alternative, leaving only search scope and truncation unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3, but the description adds real meaning: names mode returns 'name/description/category only' (more than the schema's 'compact') and clarifies limit 'caps hits'. Mode and limit behavior are therefore understood without inspecting the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Search child MCP tools by keyword'), which clearly separates it from invoke_tool and the resource-oriented siblings. It never explicitly contrasts itself with search_resources, so sibling differentiation is implied by the word 'tools' rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete when-to-use guidance: default to mode=names, switch to mode=schema for a single tool or tight query, and call mcp_status for the roster. It provides an alternative (mcp_status) but no explicit when-not-to-use condition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0invoke_toolmcp_statusread_resourcesearch_resourcessearch_toolsScored across 5 tools
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.'
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.
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.
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.
Search, vet & assemble MCP servers from your agent: verified tools, risk labels, and trust scores.
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.
Your org's AI agents, tasks, runs, search, and brain files as MCP tools and resources.
The OpenRouter for tools. One MCP connection gives any AI agent 254 hosted tools, pay per call.
