NexsFastMCP

High-performance Go framework for building Model Context Protocol (MCP) servers — protocol version 2025-06-18.

---

Overview

NexsFastMCP is a framework for building MCP servers in Go with a fluent builder API, reflection-based JSON Schema generation, and support for multiple transports (Stdio, HTTP Streamable, SSE).

It lets you expose tools, resources, and prompts to any MCP-compatible client — Claude Desktop, VS Code with Copilot, or any custom client — with minimal boilerplate.

package main

import (
    "context"
    "fmt"
    "log"

    nexsfastmcp "github.com/fsvxavier/nexs-fastmcp"
    "github.com/fsvxavier/nexs-fastmcp/pkg/tools"
)

type GreetInput struct {
    Name string `json:"name" jsonschema_description:"Name of the person to greet"`
}

func main() {
    srv := nexsfastmcp.New("hello-world",
        nexsfastmcp.WithVersion("1.0.0"),
        nexsfastmcp.WithInstructions("A demo server that greets users."),
    )

    srv.Tool("greet",
        func(_ context.Context, in GreetInput) (string, error) {
            if in.Name == "" {
                return "", fmt.Errorf("name is required")
            }
            return fmt.Sprintf("Hello, %s! Welcome to NexsFastMCP", in.Name), nil
        },
        tools.WithDescription("Greets a person by name"),
        tools.WithAnnotations(tools.ReadOnly()),
    )

    log.Fatal(srv.RunStdio(context.Background()))
}

---

Table of Contents

• Features
• Installation
• Quick Start
• Architecture
• Transports
• Examples
• Documentation
• Dependencies
• Contributing

---

Features

Feature	Description
Fluent Builder API	Chain .Tool(), .Resource(), .Prompt() for concise server setup
Reflection-based Schemas	Automatic JSON Schema generation from Go structs via struct tags
Multiple Transports	Stdio, HTTP Streamable (MCP 2025-06-18), and SSE in a single binary
Type-safe Generics	Registry[T] provides compile-time safety for components
Observability	Structured logging (zap), Prometheus metrics, OpenTelemetry tracing, health checks
Lifespan Management	Shared state initialization and teardown at server startup/shutdown
MCP Client	Built-in client for programmatically calling other MCP servers
Functional Options	WithDescription(), WithTimeout(), WithAnnotations(), etc.
Zero-config Defaults	Sensible defaults for everything — override only what you need

---

Installation

go get github.com/fsvxavier/nexs-fastmcp

Requirements: Go 1.23+

---

Quick Start

1. Create a server with a tool

srv := nexsfastmcp.New("my-server", nexsfastmcp.WithVersion("1.0.0"))

srv.Tool("add",
    func(_ context.Context, in struct {
        A float64 `json:"a"`
        B float64 `json:"b"`
    }) (float64, error) {
        return in.A + in.B, nil
    },
    tools.WithDescription("Adds two numbers"),
)

2. Add a resource

srv.TextResource("docs://readme",
    "# My Server\nThis server does math.",
    resources.WithDescription("Server documentation"),
)

3. Add a prompt

srv.Prompt("summarize",
    func(_ context.Context, in struct {
        Topic string `json:"topic"`
    }) ([]protocol.Message, error) {
        return []protocol.Message{
            protocol.UserTextMessage(fmt.Sprintf("Summarize: %s", in.Topic)),
        }, nil
    },
)

4. Run

// Stdio — for Claude Desktop and VS Code
log.Fatal(srv.RunStdio(context.Background()))

// HTTP — for web clients
log.Fatal(srv.RunHTTP(context.Background(), ":8080"))

---

Architecture

┌─────────────────────────────────────────────────┐
│                  FastMCP (Builder)               │
│  .Tool() .Resource() .Prompt() .RunStdio/HTTP()  │
└──────────────────────┬──────────────────────────┘
                       │
              ┌────────▼────────┐
              │     Server      │
              │  (Orchestrator) │
              └───┬────┬────┬───┘
          ┌───────┘    │    └───────┐
    ┌─────▼─────┐ ┌────▼────┐ ┌────▼─────┐
    │ Registry   │ │Registry │ │ Registry │
    │  <Tool>   │ │<Resource│ │ <Prompt> │
    └─────┬─────┘ └────┬────┘ └────┬─────┘
          │            │           │
    ┌─────▼────────────▼───────────▼──────┐
    │           Handler (JSON-RPC)         │
    └────────────────┬────────────────────┘
                     │
         ┌───────────┼───────────┐
    ┌────▼────┐ ┌────▼────┐ ┌───▼────┐
    │  Stdio  │ │  HTTP   │ │  SSE   │
    │Transport│ │Transport│ │Transport│
    └─────────┘ └─────────┘ └────────┘

Key packages:

Package	Responsibility
nexsfastmcp (root)	Builder API entrypoint — New(), Tool(), Resource(), Prompt(), Run*()
pkg/tools	Tool registration, schema generation, handler invocation
pkg/resources	Static resources and URI template resources
pkg/prompts	Prompt templates with typed arguments
pkg/context	Context helpers — session ID, logger, lifespan state
pkg/lifespan	Server lifecycle hooks with shared state
pkg/observability	Logging (zap), metrics (Prometheus), tracing (OpenTelemetry), health
pkg/transport/http	HTTP Streamable transport (MCP 2025-06-18)
client	MCP client for calling external MCP servers

---

Transports

Stdio (default)

For CLI-based clients such as Claude Desktop and VS Code. Reads JSON-RPC from stdin, writes to stdout; all logging goes to stderr per the MCP spec.

log.Fatal(srv.RunStdio(context.Background()))
// or with OS signal handling:
log.Fatal(srv.RunWithSignal())

HTTP Streamable

Modern HTTP-based transport per MCP 2025-06-18. Supports sessions, SSE streaming for notifications, and standard JSON-RPC over POST.

log.Fatal(srv.RunHTTP(ctx, ":8080"))

// With full options:
import httptransport "github.com/fsvxavier/nexs-fastmcp/pkg/transport/http"

err := srv.RunHTTPWithOptions(ctx, httptransport.Options{
    Addr:            ":8080",
    Path:            "/mcp",
    AllowedOrigins:  []string{"https://myapp.com"},
    ShutdownTimeout: 10 * time.Second,
})

SSE (Legacy)

Legacy Server-Sent Events transport for older MCP clients.

log.Fatal(srv.RunSSE(ctx, ":8080"))

---

Examples

Nine runnable examples are included in the examples/ directory, ordered by complexity:

Example	Directory	Description
Hello World	examples/01-hello-world/	Minimal server with one greeting tool
Calculator	examples/02-calculator/	Math tools with typed struct inputs
File Server	examples/03-file-server/	Static resources and URI templates
Prompt Templates	examples/04-prompt-templates/	Prompt registration with arguments
Context & Logging	examples/05-context-logging/	Session context and structured logging
HTTP Transport	examples/06-http-transport/	HTTP Streamable transport with options
Composition	examples/07-composition/	Combining tools, resources, and prompts
Client	examples/08-client/	Using the built-in MCP client
Lifespan	examples/09-lifespan/	Lifecycle hooks and shared state

Run any example:

cd examples/01-hello-world
go run .

Send a JSON-RPC message over stdio:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{
  "protocolVersion":"2025-06-18",
  "capabilities":{},
  "clientInfo":{"name":"test","version":"0.1"}
}}' | go run examples/01-hello-world/main.go

---

Documentation

Full documentation is in the docs/ directory:

Document	Description
Getting Started	Installation, first server, running with Claude Desktop
Tools	Registering tools, input schemas, handlers, annotations
Resources	Static resources, URI templates, MIME types
Prompts	Prompt registration, rendering, arguments
Transports	Stdio, HTTP Streamable, SSE — configuration and usage
Lifespan	Server lifecycle, shared state, teardown
Context	Context helpers — session, logging, lifespan access
Client	MCP client for calling servers programmatically
Schema	JSON Schema generation and validation
Observability	Logging, Prometheus metrics, OpenTelemetry tracing, health checks
Registry	Component registry, duplicate policies, filtering
Protocol	Wire types, error codes, content constructors
Examples	Walkthrough of all 9 example projects
API Reference	Complete public API surface listing

---

Dependencies

Dependency	Purpose
gofiber/fiber/v3	HTTP transport layer
google/uuid	Session ID generation
invopop/jsonschema	JSON Schema generation from Go types
prometheus/client_golang	Prometheus metrics
santhosh-tekuri/jsonschema/v6	JSON Schema validation
go.opentelemetry.io/otel	OpenTelemetry tracing
go.uber.org/zap	Structured logging

---

Contributing

Contributions are welcome. Please follow standard Go conventions:

# Format and vet
go fmt ./...
go vet ./...

# Run tests
go test ./...

# Run tests with race detection
go test -race ./...

---

License

Copyright © Your Name. Licensed under the Apache 2.0 License.