go-sdk

MCP Go SDK v0.4.0

BREAKING CHANGES

This version contains breaking changes.
See the release notes for details.

This repository contains an unreleased implementation of the official Go
software development kit (SDK) for the Model Context Protocol (MCP).

[!WARNING]
The SDK is not yet at v1.0.0 and may still be subject to incompatible API
changes. We aim to tag v1.0.0 in September, 2025. See
https://github.com/modelcontextprotocol/go-sdk/issues/328 for details.

Package documentation

The SDK consists of two importable packages:

• The
  github.com/modelcontextprotocol/go-sdk/mcp
  package defines the primary APIs for constructing and using MCP clients and
  servers.
• The
  github.com/modelcontextprotocol/go-sdk/jsonrpc package is for users implementing
  their own transports.
• The
  github.com/modelcontextprotocol/go-sdk/auth
  package provides some primitives for supporting oauth.

Getting started

To get started creating an MCP server, create an mcp.Server instance, add
features to it, and then run it over an mcp.Transport. For example, this
server adds a single simple tool, and then connects it to clients over
stdin/stdout:

package main

import (
	"context"
	"log"

	"github.com/modelcontextprotocol/go-sdk/mcp"
)

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

type Output struct {
	Greeting string `json:"greeting" jsonschema:"the greeting to tell to the user"`
}

func SayHi(ctx context.Context, req *mcp.CallToolRequest, input Input) (*mcp.CallToolResult, Output, error) {
	return nil, Output{Greeting: "Hi " + input.Name}, nil
}

func main() {
	// Create a server with a single tool.
	server := mcp.NewServer(&mcp.Implementation{Name: "greeter", Version: "v1.0.0"}, nil)
	mcp.AddTool(server, &mcp.Tool{Name: "greet", Description: "say hi"}, SayHi)
	// Run the server over stdin/stdout, until the client disconnects
	if err := server.Run(context.Background(), &mcp.StdioTransport{}); err != nil {
		log.Fatal(err)
	}
}

To communicate with that server, we can similarly create an mcp.Client and
connect it to the corresponding server, by running the server command and
communicating over its stdin/stdout:

package main

import (
	"context"
	"log"
	"os/exec"

	"github.com/modelcontextprotocol/go-sdk/mcp"
)

func main() {
	ctx := context.Background()

	// Create a new client, with no features.
	client := mcp.NewClient(&mcp.Implementation{Name: "mcp-client", Version: "v1.0.0"}, nil)

	// Connect to a server over stdin/stdout
	transport := &mcp.CommandTransport{Command: exec.Command("myserver")}
	session, err := client.Connect(ctx, transport, nil)
	if err != nil {
		log.Fatal(err)
	}
	defer session.Close()

	// Call a tool on the server.
	params := &mcp.CallToolParams{
		Name:      "greet",
		Arguments: map[string]any{"name": "you"},
	}
	res, err := session.CallTool(ctx, params)
	if err != nil {
		log.Fatalf("CallTool failed: %v", err)
	}
	if res.IsError {
		log.Fatal("tool failed")
	}
	for _, c := range res.Content {
		log.Print(c.(*mcp.TextContent).Text)
	}
}

The examples/ directory contains more example clients and
servers.

Design

The design doc for this SDK is at design.md, which was
initially reviewed at
modelcontextprotocol/discussions/364.

Further design discussion should occur in
issues (for concrete
proposals) or
discussions for
open-ended discussion. See CONTRIBUTING.md for details.

Acknowledgements

Several existing Go MCP SDKs inspired the development and design of this
official SDK, notably mcp-go, authored
by Ed Zynda. We are grateful to Ed as well as the other contributors to mcp-go,
and to authors and contributors of other SDKs such as
mcp-golang and
go-mcp. Thanks to their work, there
is a thriving ecosystem of Go MCP clients and servers.

License

This project is licensed under the MIT License - see the LICENSE
file for details.