Transport Nats
A NATS Transport implementation for modelcontextprotocol/go-sdk
Ask AI about Transport Nats
Powered by Claude Β· Grounded in docs
I know everything about Transport Nats. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
MCP NATS Transport
A NATS transport implementation for the Model Context Protocol (MCP). This enables distributed MCP communication by routing JSON-RPC messages over NATS messaging.
What This Enables
- Distributed MCP: Run MCP servers and clients across network boundaries
- Service Discovery: Leverage NATs subjects for discovery
- Load Balancing: Use NATS queue groups for automatic load distribution
- Fault Tolerance: Built-in reconnection and error recovery
- Scalability: Handle thousands of concurrent MCP connections
Installation
go get github.com/ganawaj/mcp-transport-nats
Quick Start
1. Start NATS Server
# Start NATS server
docker run -d --rm -p 4222:4222 nats:latest -DV -js
2. Create an MCP Server
package main
import (
"context"
"log"
mcpNats "github.com/ganawaj/mcp-transport-nats"
"github.com/modelcontextprotocol/go-sdk/mcp"
)
func main() {
// Create MCP server
server := mcp.NewServer(&mcp.Implementation{
Name: "my-service",
Version: "1.0.0",
}, nil)
// Add tools (see examples for details)
mcp.AddTool(server, &mcp.Tool{Name: "greet"}, greetHandler)
// Create NATS transport
transport := &mcpNats.Transport{
Subject: "mcp.my-service",
NatsURL: "nats://localhost:4222",
}
// Run server
err := server.Run(context.Background(), transport)
if err != nil {
log.Fatal(err)
}
}
3. Test with NATS CLI
# Install NATS CLI
go install github.com/nats-io/natscli/nats@latest
# Initialize MCP session
nats request mcp.my-service '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{}},"id":1}'
# Send initialized notification
nats pub mcp.my-service '{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}'
# List available tools
nats request mcp.my-service '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":2}'
# Call a tool
nats request mcp.my-service '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"greet","arguments":{"name":"World"}},"id":3}'
Configuration
Transport Options
transport := &mcp_nats.Transport{
// Required: NATS subject to listen on
// Must be a valid NATs subject: https://docs.nats.io/nats-concepts/subjects
Subject: "mcp.my-service",
// Optional: NATS server URL (default: nats://localhost:4222)
NatsURL: "nats://localhost:4222",
// Optional: Queue group for load balancing
// See: https://docs.nats.io/nats-concepts/core-nats/queue
Queue: "my-service-workers",
// Optional: Custom logger
Logger: slog.Default().With("service", "my-service"),
// Optional: Connection timeouts
ConnectTimeout: 30 * time.Second,
ReconnectWait: 5 * time.Second,
MaxReconnects: -1, // Unlimited
}
Subject Naming Conventions
The MCP listens on a typical Nats Subject. This include both wildcards, '*' and '>'.
mcp.<service>.<instance> # Single service instance
mcp.<domain>.<service> # Service within a domain
mcp.agents.<agent-id> # Individual agents (A2A discovery)
mcp.tools.<tool-name> # Tool-specific services
Examples:
mcp.agents.sales-bot-1- Sales agent instancemcp.finance.calculator- Finance calculation service
Examples
Simple Server with Tool
See examples/simple-server/ for a complete working example.
Testing the Example
# Terminal 1: Start NATS server
docker run -d --rm -p 4222:4222 nats:latest -DV -js
# Terminal 2: Run the example
cd examples/simple-server
go run main.go
# Terminal 3: Test the server
# Initialize session
nats request mcp.greeter '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{}},"id":1}'
# Send initialized notification
nats pub mcp.greeter '{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}'
# List tools
nats request mcp.greeter '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":2}'
# Call the greet tool
nats request mcp.greeter '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"greet","arguments":{"name":"Alice"}},"id":3}'
# Expected response:
# {"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"Hi Alice! π"}],"structuredContent":{}}}
Architecture
How It Works
βββββββββββββββ NATS βββββββββββββββ
β MCP Client βββββββββββββΊ β MCP Server β
β β JSON-RPC β β
βββββββββββββββ over βββββββββββββββ
NATS
- MCP Server uses NATS transport and subscribes to a subject
- MCP Client sends JSON-RPC requests to the subject
- NATS routes messages and handles replies automatically
- Transport handles encoding/decoding and session management
Message Flow
Client NATS Server
β β β
ββββ JSON-RPC βββββββΊβ β
β Request βββββ Forward ββββββΊβ
β β βββββ
β β β β Process
β β β β Request
β β βββββ
β βββββ Response ββββββ
ββββ JSON-RPC βββββββ β
Response
Load Balancing
Use NATS queue groups for automatic load balancing:
// Multiple instances with same queue group
transport := &mcp_nats.Transport{
Subject: "mcp.my-service",
Queue: "my-service-workers", // Same queue group
}
NATS automatically distributes requests across instances in the same queue group. Queue groups guarantees that the message is only delivered once for all subscribers to the queue.
Monitoring and Observability
The transport provides structured logging for observability:
import "log/slog"
logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
Level: slog.LevelDebug,
}))
transport := &mcp_nats.Transport{
Subject: "mcp.my-service",
Logger: logger,
}
Log Events
- Connection establishment and health
- Message routing and session management
- Error conditions and recovery
- Performance metrics
π License
This project is licensed under the MIT License - see the LICENSE file for details.
Related Projects
- MCP Go SDK - Official MCP Go implementation
- NATS Server - High-performance messaging system
