MCP Tool Flow Architecture

Complete self-hosted MCP (Model Context Protocol) infrastructure for Claude.ai integration with 95% token reduction.

Overview

This repository documents the complete MCP tool flow architecture that enables Claude.ai to access 350+ tools while consuming only ~800 tokens (instead of ~40,000).

Claude.ai → mcp-front (OAuth) → mcp-tool-filter (semantic) → mcp-name-bridge → Context Forge → [22 MCP servers]

Why This Architecture?

Problem: Token Explosion

Connecting Claude.ai directly to 350+ tools would consume ~40,000 tokens before any conversation starts, severely limiting conversation length.

Solution: 4-Layer Architecture

OAuth Gateway - Secure authentication via Google OAuth
Semantic Tool Filter - Exposes only 3 meta-tools, finds relevant tools on-demand
Name Bridge - Translates naming conventions between systems
Context Forge - Aggregates all MCP servers into unified endpoint

Result

| Metric | Before | After | Savings | |--------|--------|-------|--------| | Token Usage | ~40,000 | ~800 | 98% | | Tools Visible | 350+ | 3 | Semantic search | | Security | None | OAuth 2.0 | Enterprise-ready |

Architecture Diagram

┌─────────────────────────────────────────────────────────────────┐
│                         CLAUDE.AI                                │
│              Sees only 3 tools (~800 tokens):                    │
│         search_tools, execute_tool, list_all_tools               │
└─────────────────────────────────────────────────────────────────┘
                              │ HTTPS
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    mcp.millyweb.com                              │
│              Traefik (SSL Termination)                           │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                 mcp-front (Port 8088)                            │
│                                                                  │
│  • Google OAuth 2.0 authentication                               │
│  • JWT token validation                                          │
│  • Routes to tool-filter                                         │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│              mcp-tool-filter-cf (Port 8098)                      │
│                 TOKEN OPTIMIZATION LAYER                         │
│                                                                  │
│  • Exposes only 3 meta-tools to Claude                           │
│  • search_tools(query) - Semantic search with embeddings         │
│  • execute_tool(name, args) - Execute any tool by name           │
│  • list_all_tools() - Browse all available tools                 │
│  • Uses local MiniLM embeddings (no API key needed)              │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│               mcp-name-bridge (Port 8080)                        │
│                 CONVENTION CONVERTER                             │
│                                                                  │
│  • Translates tool names between systems                         │
│  • gateway__ssh_execute → gateway-ssh-execute                    │
│  • Handles Context Forge slug conventions                        │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│             Context Forge (Port 4444/8099)                       │
│                 MCP GATEWAY AGGREGATOR                           │
│                                                                  │
│  • IBM's open-source MCP gateway                                 │
│  • Aggregates 22 MCP servers                                     │
│  • 350+ tools available                                          │
│  • Admin UI at :4444                                             │
└─────────────────────────────────────────────────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        ▼                     ▼                     ▼
┌───────────────┐   ┌───────────────┐   ┌───────────────┐
│   Filesystem  │   │    GitHub     │   │  mcp-gateway  │
│     Git       │   │    Slack      │   │   (SSH/VPS)   │
│   PostgreSQL  │   │   LinkedIn    │   │               │
│     Fetch     │   │   Puppeteer   │   │ • ssh_execute │
│  BraveSearch  │   │  Browserless  │   │ • ssh_read    │
│     ...       │   │     ...       │   │ • ssh_write   │
└───────────────┘   └───────────────┘   └───────────────┘

Quick Start

Prerequisites

Docker & Docker Compose
Domain with DNS pointing to your server
Google OAuth credentials (for authentication)
Traefik reverse proxy (or similar)

1. Clone Repository

git clone https://github.com/rdmilly/mcp-tool-flow.git
cd mcp-tool-flow

2. Deploy Context Forge (MCP Aggregator)

cd contextforge
cp .env.example .env
# Edit .env with your credentials
docker-compose up -d

3. Deploy Name Bridge

cd ../mcp-name-bridge
docker-compose up -d

4. Deploy Tool Filter

cd ../mcp-tool-filter
cp .env.example .env
# Edit .env
docker-compose up -d

5. Deploy OAuth Gateway

cd ../mcp-front
cp .env.example .env
# Edit .env with Google OAuth credentials
docker-compose up -d

6. Register in Claude.ai

Go to Claude.ai Settings → Connectors
Add custom connector: https://your-domain.com/mcp/sse
Complete OAuth flow
Start using 350+ tools!

Components

| Component | Port | Purpose | Documentation | |-----------|------|---------|---------------| | mcp-front | 8088 | OAuth gateway | mcp-front/README.md | | mcp-tool-filter | 8098 | Semantic filtering | mcp-tool-filter/README.md | | mcp-name-bridge | 8080 | Name translation | mcp-name-bridge/README.md | | contextforge | 4444, 8099 | MCP aggregation | contextforge/README.md | | mcp-gateway | 8086 | SSH/VPS tools | mcp-gateway/README.md |

Registered MCP Servers (22 total)

| Server | Tools | Description | |--------|-------|-------------| | Filesystem | 15+ | File operations | | Git | 10+ | Git operations | | PostgreSQL | 10+ | Database queries | | GitHub | 30+ | Repository management | | Slack | 15+ | Messaging | | Docker | 20+ | Container management | | Puppeteer | 10+ | Browser automation | | Browserless | 5+ | Headless browsing | | LinkedIn | 5+ | Social posting | | Gateway (SSH) | 9 | SSH/VPS management | | ...and 12 more | | |

API Reference

Tool Filter Endpoints

# Health check
curl http://localhost:8098/health

# List all tools (paginated)
curl -X POST http://localhost:8098/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Context Forge Admin API

# List gateways
curl -u admin:PASSWORD http://localhost:4444/gateways

# Register new gateway
curl -X POST http://localhost:4444/gateways \
  -u admin:PASSWORD \
  -H "Content-Type: application/json" \
  -d '{"name":"MyServer","url":"http://server:8080/mcp","transport":"STREAMABLEHTTP"}'

# List all tools
curl -u admin:PASSWORD "http://localhost:4444/tools?limit=500"

Network Configuration

All components communicate over a shared Docker network:

networks:
  mcp-network:
    external: true

Create it once:

docker network create mcp-network

Troubleshooting

Tools not showing up

Check Context Forge has gateways registered: curl -u admin:PASS http://localhost:4444/gateways
Check tool-filter can reach name-bridge: docker logs mcp-tool-filter-cf
Verify name-bridge health: curl http://localhost:8080/health

OAuth not working

Verify Google OAuth credentials in mcp-front .env
Check redirect URI matches your domain
Review mcp-front logs: docker logs mcp-front

SSH tools failing

Verify mcp-gateway is registered with Context Forge
Check SSH keys are mounted: docker exec mcp-gateway ls /ssh
Test SSH connection: docker exec mcp-gateway cat /app/src/index.js

Contributing

Contributions welcome! Please read CONTRIBUTING.md first.

License

MIT License - see LICENSE for details.

Credits

IBM Context Forge - MCP gateway aggregator
Portkey MCP Tool Filter - Semantic filtering library
mcp-front - OAuth gateway

Built by Ryan Milly as part of the Millyweb AI infrastructure project.

MCP Servers