Goblin MCP Gateway

Developer-first MCP gateway that aggregates multiple MCP servers behind a single unified endpoint

[][license-url]

Blazing-fast performance • Hot reload • Enterprise-ready

---

About

Goblin is a production-ready Model Context Protocol (MCP) gateway that solves tool sprawl, context bloat, and brittle integrations in agentic AI systems. Built with Bun, TypeScript, Hono, and the MCP SDK, Goblin provides sub-50ms latency targets and a developer-first experience including a real-time TUI dashboard, structured logging, and comprehensive observability.

Why Goblin?

• Unified Interface: Single endpoint aggregating tools, prompts, and resources from multiple MCP backends
• Hot Reload: Configuration changes applied atomically without restart
• Multi-Transport: STDIO, HTTP, SSE, and Streamable HTTP with automatic connection pooling
• Enterprise Ready: 1000+ tests, smoke tests for CI, performance benchmarks

---

Features

Core Gateway	Management	Security	Observability
🔌 Unified Aggregation	🎛️ TUI Dashboard	✅ Secure by Default	📊 Structured Logging
🛣️ Intelligent Routing	⚡ Hot Reload	🔐 API Key Auth	📈 Custom Metrics
🚀 Multi-Transport	🔧 CLI Commands	🛡️ RBAC Ready	🔍 Real-time TUI
📦 Virtual Tools	🖥️ Interactive TUI	📋 Audit Logging	🚨 Health Checks

Core Capabilities

• 🔌 Unified Aggregation — Single endpoint for tools, prompts, and resources from multiple MCP servers
• 🛣️ Intelligent Routing — Namespaced tool calls with timeout enforcement and error mapping
• 🚀 Multi-Transport — STDIO, HTTP, SSE, and Streamable HTTP with automatic connection pooling
• ⚡ Hot Reload — Configuration changes applied atomically without restart (HTTP mode) or via SIGHUP (STDIO mode)
• 📊 Full Observability — Structured logging, custom metrics, and real-time TUI dashboard
• ✅ Enterprise Ready — 1000+ tests, smoke tests for CI, performance benchmarks

---

Quick Start

1. Install

git clone https://github.com/TalkingThreads/goblin.git
cd goblin
bun install

2. Configure

Create a config.json file:

{
  "servers": [
    {
      "name": "filesystem",
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "enabled": true
    }
  ],
  "gateway": {
    "port": 3000,
    "host": "127.0.0.1"
  }
}

3. Run

# Development mode (with hot reload)
bun run dev

# Production mode
bun run build
bun run start

# With TUI dashboard
goblin start --tui

# STDIO mode (for Claude CLI integration)
goblin stdio

That's it! Goblin is now running at http://127.0.0.1:3000.

• HTTP: http://127.0.0.1:3000/mcp
• SSE: http://127.0.0.1:3000/sse

---

Installation

From Source

git clone https://github.com/TalkingThreads/goblin.git
cd goblin
bun install
bun run build

Prerequisites

Tool	Version	Required
Bun	>= 1.3.8	✅ Yes
Node.js	>= 20.0.0	For CLI only

---

Documentation

Topic	Description
📚 Getting Started	Step-by-step installation and configuration
🏗️ Architecture	System design and component overview
💻 CLI Reference	Complete CLI commands documentation
🌐 API Reference	HTTP endpoints and API documentation
⚙️ Configuration	Complete configuration reference
🔧 Troubleshooting	Common issues and solutions

---

CLI Commands

Gateway Management

goblin start              # Start the gateway (default: HTTP mode)
goblin start --tui       # Start with TUI dashboard
goblin start --port 8080 # Custom port
goblin restart           # Graceful restart
goblin stop              # Graceful shutdown

Server Management

goblin servers                    # List all servers
goblin servers add <name> <type>  # Add a new server
goblin servers remove <name>      # Remove a server
goblin servers enable <name>      # Enable a disabled server
goblin servers disable <name>     # Disable a server

Tool Operations

goblin tools list                 # List all available tools
goblin tools invoke <name> --args '{"path": "/tmp"}'
goblin tools describe <name>      # Show tool schema

Configuration

goblin config validate            # Validate configuration
goblin config show                # Display current config
goblin config reload              # Hot reload config

Monitoring

goblin status                     # Gateway status
goblin health                     # Health check
goblin logs                       # Show logs
goblin logs -f                    # Follow logs
goblin metrics                    # Performance metrics

Shell Completion

# Bash
goblin completion bash >> ~/.bashrc

# Zsh
goblin completion zsh >> ~/.zshrc

# Fish
goblin completion fish > ~/.config/fish/completions/goblin.fish

See CLI Reference for complete documentation.

---

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      Goblin MCP Gateway                       │
│                                                              │
│  ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐ │
│  │  Client  │──▶│  HTTP    │──▶│  Router  │──▶│ Registry │ │
│  │  (MCP)   │   │ Gateway  │   │          │   │          │ │
│  └──────────┘   └──────────┘   └──────────┘   └──────────┘ │
│                                      │              │        │
│                                      ▼              ▼        │
│  ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐ │
│  │  Client  │◀──│   TUI    │◀──│ Metrics  │◀──│ Transport│ │
│  │  (MCP)   │   │Dashboard │   │          │   │   Pool   │ │
│  └──────────┘   └──────────┘   └──────────┘   └──────────┘ │
│                                                              │
└─────────────────────────────────────────────────────────────┘
         │                    │                    │
         ▼                    ▼                    ▼
  ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
  │ MCP Server 1 │     │ MCP Server 2 │     │ MCP Server N │
  │ (Filesystem) │     │ (Git)        │     │ (Custom)     │
  └──────────────┘     └──────────────┘     └──────────────┘

See Architecture for detailed component documentation.

---

Client Transport Types

STDIO Transport

Local subprocess-based transport for running MCP servers as child processes:

{
  "name": "filesystem",
  "transport": "stdio",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
  "enabled": true
}

HTTP Transport

Simple HTTP transport for connecting to HTTP-based MCP servers:

{
  "name": "remote-server",
  "transport": "http",
  "url": "http://localhost:3001/mcp",
  "enabled": true
}

SSE Transport

Server-Sent Events transport for server-push notifications:

{
  "name": "sse-server",
  "transport": "sse",
  "url": "http://localhost:3002/sse",
  "enabled": true
}

Streamable HTTP Transport

Stateful HTTP transport with session management, automatic reconnection, and custom headers:

{
  "name": "streamable-server",
  "transport": "streamablehttp",
  "url": "http://localhost:3003/mcp",
  "headers": {
    "Authorization": "Bearer your-token-here"
  },
  "reconnect": {
    "enabled": true,
    "delay": 1000,
    "maxRetries": 5,
    "backoffMultiplier": 2
  },
  "enabled": true
}

---

Server Lifecycle Modes

Goblin supports three connection lifecycle modes for backend MCP servers:

Mode	Description	Use Case
stateful (default)	Connections kept alive indefinitely, reused across requests	High-frequency tool calls, persistent sessions
smart	Connections kept alive, evicted after 60 seconds of idle time	Balance between responsiveness and resource efficiency
stateless	Connections created per request, evicted quickly after use	Low-frequency calls, resource-constrained environments

Mode Configuration

Add the mode property to your server configuration:

{
  "name": "filesystem",
  "transport": "stdio",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
  "mode": "smart",
  "enabled": true
}

• stateful (default): Best for servers that are called frequently
• smart: Recommended default - auto-cleanup after 60s idle
• stateless: Best for minimizing memory usage with occasional calls

---

Technology Stack

Component	Technology	Purpose
Runtime	Bun	Fast JavaScript runtime
MCP Core	@modelcontextprotocol/sdk	Protocol implementation
HTTP Server	Hono	Lightweight web framework
Validation	Zod	Runtime type validation
Logging	Pino	Structured JSON logging
Metrics	Custom (zero-dep)	In-memory metrics
CLI	Commander.js	Command-line interface
TUI	Ink + React	Terminal UI

---

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Workflow

1. Read AGENTS.md for spec-driven development process
2. Create a change proposal for new features
3. Write tests for your changes
4. Ensure all tests pass: bun test
5. Submit a pull request

Pre-commit Hooks

This project uses Husky for pre-commit hooks:

# Install hooks (runs automatically after bun install)
bun run prepare

Hooks check:

• ✅ TypeScript type checking (bun run typecheck)
• ✅ Biome linting (bun run lint)
• ✅ Unit tests (bun test tests/unit/)

---

Support

• 📖️ Documentation
• 💬 GitHub Discussions
• 🐛 GitHub Issues
• 🔒 Security Policy

---

License

MIT © TalkingThreads

---

Related Documentation

Document	Description
CHANGELOG.md	Version history and release notes
MAINTAINERS.md	Project maintainers
CODE_OF_CONDUCT.md	Community guidelines
openspec/project.md	Project context and design

---

Built with ❤️ by the TalkingThreads team