go-mcp-host

A Go-based Model Context Protocol (MCP) Host service with AI agent capabilities. This service acts as an intelligent agent that connects to multiple MCP servers, integrates with Ollama (OpenAI-compatible LLM), and provides an agentic AI experience to users.

Go Version License

Features

Quick Start

Option 1: Use as a Standalone Service

Deploy go-mcp-host as a microservice in your infrastructure.

Prerequisites

Run Locally

# Clone the repository
git clone https://github.com/d4l-data4life/go-mcp-host.git
cd go-mcp-host

# Copy and configure
cp config.example.yaml config.yaml
# Edit config.yaml to add your MCP servers

# Start PostgreSQL
make docker-database

# Run the service
make run

The service will be available at http://localhost:8080.

Deploy to Kubernetes

# See detailed deployment guide
cd deploy
cat README.md

# Quick deploy
helm install go-mcp-host ./helm-chart \
  -f examples/local/values.yaml \
  --namespace mcp-host

See deploy/README.md for full deployment documentation.

Option 2: Use as a Go Library

Embed MCP Host functionality into your own Go application.

Installation

go get github.com/d4l-data4life/go-mcp-host

Basic Usage

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/d4l-data4life/go-mcp-host/pkg/config"
    "github.com/d4l-data4life/go-mcp-host/pkg/mcphost"
    "github.com/google/uuid"
    "gorm.io/driver/postgres"
    "gorm.io/gorm"
)

func main() {
    // Setup database
    db, err := gorm.Open(postgres.Open("host=localhost port=5432 user=mcphost dbname=mcphost password=postgres sslmode=disable"), &gorm.Config{})
    if err != nil {
        log.Fatal(err)
    }

    // Create MCP Host
    host, err := mcphost.NewHost(context.Background(), mcphost.Config{
        MCPServers: []config.MCPServerConfig{
            {
                Name:    "weather",
                Type:    "stdio",
                Command: "npx",
                Args:    []string{"-y", "@h1deya/mcp-server-weather"},
                Enabled: true,
                Description: "Weather information server",
            },
        },
        LLMEndpoint: "http://localhost:11434",
        DB:          db,
    })
    if err != nil {
        log.Fatal(err)
    }

    // Chat with the agent
    response, err := host.Chat(context.Background(), mcphost.ChatRequest{
        ConversationID: uuid.New(),
        UserID:         uuid.New(),
        UserMessage:    "What's the weather in New York?",
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(response.Message.Content)
}

Run examples:

# Simple library usage
go run examples/simple_library/simple_library.go

# Web server integration
go run examples/embed_in_webserver/embed_in_webserver.go

# Agent package (mid-level)
go run examples/agent_chat/agent_chat.go

# Low-level MCP usage
go run examples/ollama_with_mcp/ollama_with_mcp.go

See examples/README.md for detailed documentation.

Architecture

┌────────────────────────────────────────────────────┐
│               Frontend (React/API)                 │
└────────────────────────┬───────────────────────────┘
                         │ HTTP/WebSocket
┌────────────────────────▼───────────────────────────┐
│                   go-mcp-host                      │
│  ┌───────────────────────────────────────────────┐ │
│  │  Agent Orchestrator                           │ │
│  │  - Context gathering                          │ │
│  │  - Tool execution loop                        │ │
│  │  - Response generation                        │ │
│  └───────────┬───────────────────────┬───────────┘ │
│              │                       │             │
│  ┌───────────▼──────────┐  ┌─────────▼──────────┐  │
│  │  MCP Manager         │  │  LLM Client        │  │
│  │  - Session mgmt      │  │  - Ollama API      │  │
│  │  - Client pooling    │  │  - Function calls  │  │
│  └───────────┬──────────┘  └────────────────────┘  │
│              │                                     │
└──────────────┼─────────────────────────────────────┘
               │
    ┌──────────┼──────────┐
    │          │          │
┌───▼───┐  ┌───▼───┐  ┌───▼───┐
│ MCP   │  │ MCP   │  │ MCP   │
│Server1│  │Server2│  │Server3│
│(stdio)│  │(HTTP) │  │(stdio)│
└───────┘  └───────┘  └───────┘

Configuration

MCP Servers

Configure MCP servers in config.yaml:

mcp_servers:
  # Stdio server example
  - name: weather
    type: stdio
    command: npx
    args:
      - "-y"
      - "@h1deya/mcp-server-weather"
    enabled: true
    description: "Weather information server"
  
  # HTTP server example
  - name: my-api
    type: http
    url: "https://api.example.com/mcp"
    headers:
      X-API-Key: "your-api-key"
    forwardBearer: true  # Forward user's bearer token
    enabled: true
    description: "My custom MCP server"

Environment Variables

Key environment variables:

See config.example.yaml for all options.

API Documentation

REST Endpoints

See swagger/api.yml for the full API specification.

Development

Prerequisites

Building

# Build binary
make build

# Build Docker image
make docker-build

# Run tests
make test

# Run linter
make lint

Project Structure

go-mcp-host/
├── cmd/
│   └── api/              # Main application entry point
├── pkg/
│   ├── agent/            # Agent orchestration logic
│   ├── mcp/              # MCP protocol implementation
│   │   ├── client/       # MCP client core
│   │   ├── manager/      # Session management
│   │   ├── protocol/     # Protocol types
│   │   └── transport/    # Stdio/HTTP transports
│   ├── llm/              # LLM integration (Ollama)
│   ├── handlers/         # HTTP handlers
│   ├── models/           # Database models
│   ├── config/           # Configuration
│   ├── auth/             # Authentication
│   ├── server/           # HTTP server setup
│   └── mcphost/          # Public API for library usage
├── deploy/
│   ├── helm-chart/       # Kubernetes Helm chart
│   └── examples/         # Example configurations
├── docs/                 # Additional documentation
├── examples/             # Usage examples
├── sql/                  # Database migrations
└── swagger/              # API specification

Testing

# Run all tests
make test

# Run with coverage
make test-coverage

# Run integration tests (requires running database)
make docker-database
make test-integration

Contributing

Contributions are welcome! Please:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Code Standards

See .cursorrules for detailed coding standards.

Documentation

MCP Resources

License

Apache License 2.0 - see LICENSE for details.

Acknowledgments

Support

Made with ❤️ by Data4Life