ThinMCP

ThinMCP is an MCP gateway that exposes many upstream MCP servers through a stable two-tool interface:

• search()

• execute()

Instead of loading every upstream tool definition into model context, ThinMCP keeps a local catalog, lets the model discover tools on demand, and forwards only the calls it needs to make.

Why ThinMCP

Connecting multiple MCP servers directly to a model increases context size as tool count grows. ThinMCP keeps the model-facing surface area fixed while still allowing access to a large tool ecosystem.

The result is a simpler integration point for clients and a more predictable runtime shape for production deployments.

Architecture

flowchart LR
    A["LLM or MCP Client"] --> B["ThinMCP Gateway"]
    B --> C["Local Catalog"]
    B --> D["Execution Layer"]
    D --> E["Schema Validation"]
    E --> F["Upstream MCP Servers"]
    G["Sync Process"] --> F
    G --> C
    G --> H["Snapshots"]

Key Capabilities

• Fixed two-tool interface for the model

• Support for HTTP and stdio upstream servers

• Local SQLite-backed catalog for discovery

• Input validation before upstream execution

• Sandboxed execution for gateway tool calls

• HTTP transport with health and metrics endpoints

• Periodic sync of upstream tool metadata

Quick Start

npm install
npm run build
cp config/mcp-sources.example.yaml config/mcp-sources.yaml

Edit config/mcp-sources.yaml, then sync and start:

npm run sync
npm start

HTTP mode:

npm start -- --transport http --port 8787

Validate the setup:

npm run doctor

Configuration

ThinMCP reads config/mcp-sources.yaml. Each upstream server can use either http or stdio transport.

Minimal example:

servers:
  - id: exa
    name: Exa MCP
    transport: http
    url: https://mcp.exa.ai/mcp
    auth:
      type: bearer_env
      env: EXA_API_KEY
    allowTools: ["*"]

  - id: local-fs
    name: Local Filesystem MCP
    transport: stdio
    command: npx
    args:
      - -y
      - "@modelcontextprotocol/server-filesystem"
      - /tmp
    cwd: .
    allowTools:
      - "filesystem.*"

sync:
  intervalSeconds: 300
  onStart: true

runtime:
  codeTimeoutMs: 15000
  maxCodeLength: 20000
  maxResultChars: 60000

catalog:
  dbPath: ../data/thinmcp.db
  snapshotDir: ../snapshots

Use allowTools to keep each upstream server scoped to the tools you actually want exposed through the gateway.

Running ThinMCP

Development:

npm run dev

Production build:

npm run build
npm start

HTTP mode:

npm start -- --transport http --host 127.0.0.1 --port 8787

Available HTTP endpoints:

• /mcp

• /healthz

• /metrics

Operations

Common commands:

npm run build
npm run sync
npm run doctor
npm test
THINMCP_RUN_E2E=1 npm run test:e2e

Operational guidance:

• Keep upstream credentials in environment variables

• Restrict allowTools to the smallest useful surface area

• Enable HTTP auth and rate limiting when exposing the gateway beyond local development

• Run npm run sync as part of deployment or startup validation if catalog freshness matters

Client Integration

Client examples are documented in docs/CLIENT_INTEGRATIONS.md.

License

ISC