ThinMCP

ThinMCP is a local MCP gateway that compresses many upstream MCP servers into two tools:

• search()
• execute()

You give your model only ThinMCP. ThinMCP keeps the full upstream tool surface out of model context and exposes a compact, code-driven interface.

Current Status

Progress Log

• Project scaffold (TypeScript, MCP SDK, config layout)
• Local catalog store (SQLite) and snapshot persistence
• Upstream MCP sync pipeline (tools/list -> normalized catalog)
• search() and execute() tool registration in gateway MCP server
• On-demand refresh when execute() sees stale or missing tool metadata
• Basic sandbox hardening (frozen runtime globals + timeout + code-length limit)
• Targeted sync for one upstream with --server <id>
• doctor command to validate config + auth env wiring
• Optional HTTP transport for ThinMCP server (--transport http)
• execute() argument validation against cached tool input schemas
• Non-text/large tool outputs normalized before model return
• Worker-isolated sandbox runtime with memory limits and hard termination
• Automated test suite (npm test) for sandbox/proxy/validation/output shaping
• Client integration guide (docs/CLIENT_INTEGRATIONS.md)
• Upstream MCP support over stdio in addition to Streamable HTTP
• HTTP gateway auth + rate limits (--http-auth-token*, --http-rate-*)
• Real-upstream e2e test entrypoint (npm run test:e2e)

Architecture

Model Client
  -> ThinMCP MCP Server (search, execute)
      -> Search runtime (catalog API over SQLite)
      -> Execute runtime (tool.call -> MCP proxy)
          -> Upstream MCP servers

Sync scheduler
  -> tools/list from upstreams
  -> snapshots/*.json
  -> normalized catalog in SQLite

Configure Upstream MCP Sources

Edit /Users/sri/Desktop/silly_experiments/ThinMCP/config/mcp-sources.yaml.

Reference template: /Users/sri/Desktop/silly_experiments/ThinMCP/config/mcp-sources.example.yaml.

Auth tokens are read from environment variables when auth.type = bearer_env.

Run

cd /Users/sri/Desktop/silly_experiments/ThinMCP
npm install
npm run typecheck
npm run build
npm test
npm run test:e2e   # runs only if THINMCP_RUN_E2E=1

Sync only:

npm run sync

Sync only for a single server:

npm run sync -- --server cloudflare

Start ThinMCP MCP server (stdio):

npm run dev

Start ThinMCP MCP server over HTTP (Streamable HTTP):

npm run dev:http

Custom host/port:

npm run dev -- --transport http --host 0.0.0.0 --port 8787

HTTP auth + rate limit options:

npm run dev -- \
  --transport http \
  --http-auth-token-env THINMCP_HTTP_TOKEN \
  --http-rate-limit 120 \
  --http-rate-window-seconds 60

Or set THINMCP_HTTP_TOKEN directly in environment.

Validate local setup:

npm run doctor

Example Usage in Model Tool Calls

search()

async () => {
  const tools = catalog.findTools({ query: "dns", limit: 10 });
  return tools.map((t) => ({ serverId: t.serverId, toolName: t.toolName }));
}

execute()

async () => {
  const result = await tool.call({
    serverId: "cloudflare",
    name: "zones.list",
    arguments: { account_id: "abc123" }
  });

  return result;
}

Notes

• ThinMCP currently supports upstream MCP servers over Streamable HTTP.
• ThinMCP supports upstream MCP servers over both Streamable HTTP and stdio transports.
• Sandboxing runs in a dedicated worker with memory limits and wall-clock termination, still intended for local trusted usage rather than hostile multi-tenant workloads.
• Client setup examples are in /Users/sri/Desktop/silly_experiments/ThinMCP/docs/CLIENT_INTEGRATIONS.md.
• Real-upstream e2e tests are opt-in: set THINMCP_RUN_E2E=1 and configure enabled servers (plus tokens) in config.