@vibe-agent-toolkit/gateway-mcp weekly downloads statistics

@vibe-agent-toolkit/gateway-mcp

MCP Gateway for exposing VAT agents through the Model Context Protocol, enabling orchestration by LLM systems like Claude Desktop.

Features

• Stdio Transport - Native integration with Claude Desktop and other MCP clients
• Stateless Agent Support - Pure Function Tools and One-Shot LLM Analyzers
• Multi-Agent Servers - Expose multiple agents through a single MCP server
• Runtime Agnostic - Works with any VAT runtime adapter (Vercel AI SDK, OpenAI, LangChain, Claude Agent SDK)
• Type-Safe - Full TypeScript support with branded session IDs
• Error Classification - Distinguishes retryable vs non-retryable errors for intelligent retry logic
• Observability Ready - Hooks for OpenTelemetry integration (console logger included)

Installation

# Using bun
bun add @vibe-agent-toolkit/gateway-mcp

# Using npm
npm install @vibe-agent-toolkit/gateway-mcp

# Using pnpm
pnpm add @vibe-agent-toolkit/gateway-mcp

Quick Start

Single Agent Server

Expose a single VAT agent via MCP stdio transport:

import { StdioMCPGateway, NoOpObservabilityProvider } from '@vibe-agent-toolkit/gateway-mcp';
import { haikuValidator } from '@vibe-agent-toolkit/vat-example-cat-agents';

const gateway = new StdioMCPGateway({
  name: 'haiku-validator-server',
  version: '1.0.0',
  agents: [
    {
      name: 'haiku-validator',
      agent: haikuValidator,
      runtime: null, // Pure function, no runtime needed
    },
  ],
  observability: new NoOpObservabilityProvider(),
});

await gateway.start();

Run with:

bun run my-server.ts

Multi-Agent Server

Expose multiple agents through one MCP server:

import { StdioMCPGateway, NoOpObservabilityProvider } from '@vibe-agent-toolkit/gateway-mcp';
import { haikuValidator, photoAnalyzer } from '@vibe-agent-toolkit/vat-example-cat-agents';

const gateway = new StdioMCPGateway({
  name: 'vat-agents',
  version: '1.0.0',
  agents: [
    {
      name: 'haiku-validator',
      agent: haikuValidator,
      runtime: null, // Pure function
    },
    {
      name: 'photo-analyzer',
      agent: photoAnalyzer,
      runtime: null, // Mock mode
    },
  ],
  observability: new NoOpObservabilityProvider(),
});

await gateway.start();

Claude Desktop Configuration

Add to ~/.claude/config.json:

{
  "mcpServers": {
    "vat-agents": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/your/server.ts"]
    }
  }
}

Notes:

• Use absolute paths (Claude Desktop doesn't expand ~ or relative paths)
• Restart Claude Desktop after updating config
• Check logs in Claude Desktop developer console if server doesn't connect

Architecture Overview

Design Principles

1. MCP is an interface, not a runtime - Gateway exposes agents but doesn't execute them
2. Gateway discovers configured agents - System startup registers agents, gateway provides access
3. Respect runtime patterns - Each runtime manages state its own way (LangGraph checkpointers, OpenAI threads, etc.)
4. Archetype-aware - Different agent types need different interface patterns (stateless vs stateful)
5. Separation of concerns - MCP handles protocol translation and routing, runtimes handle execution and state

Layers

┌─────────────────────────────────────────────────┐
│  External Systems (Claude Desktop, etc.)        │
└─────────────────────────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────────┐
│  Interface Layer (Gateway)                      │
│  ├─ MCP Server (stdio/HTTP)                     │
│  └─ Stateless Adapter                           │
└─────────────────────────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────────┐
│  VAT Agents (business logic)                    │
│  ├─ Pure Function Tools                         │
│  └─ One-Shot LLM Analyzers                      │
└─────────────────────────────────────────────────┘

Stdio Protocol Compliance

Critical constraint for Claude Desktop integration:

• stdout - JSON-RPC protocol messages ONLY (MCP spec requirement)
• stderr - All logs, debug output, errors
• Process lifetime - Server runs until stdin closes (natural stdio connection lifetime)

Violating stdout purity breaks MCP clients with JSON parse errors. All logging infrastructure must write to stderr.

Package-Scoped Collections

Agents are discovered via npm package exports:

// Package: @my-scope/my-agents
// Export: /mcp-collections

export const myAgents: MCPCollection = {
  name: 'my-agents',
  description: 'My agent collection',
  agents: [
    { name: 'agent-1', agent: agent1, description: '...' },
    { name: 'agent-2', agent: agent2, description: '...' },
  ],
};

export const collections: Record<string, MCPCollection> = {
  'my-agents': myAgents,
};

export const defaultCollection = myAgents;

CLI command: vat mcp serve @my-scope/my-agents

Future Enhancement: Global discovery registry with versioning.

Key Concepts

Gateway is Passive - Agents are already instantiated with their runtimes. The gateway discovers them and exposes them via MCP protocol.

Archetype-Aware - Different agent archetypes map to different MCP patterns (stateless tools, conversational agents, orchestrations, etc.)

Runtime Separation - MCP handles protocol translation and routing. Runtimes handle execution and state management.

Supported Archetypes

Pure Function Tool

Archetype: pure-function-tool

Direct synchronous functions with no LLM calls or external state.

MCP Mapping:

• One MCP tool = One VAT agent
• No session state
• Direct pass-through execution

Example: Haiku validator

One-Shot LLM Analyzer

Archetype: one-shot-llm-analyzer

Single LLM call to analyze input and return structured output.…