Watch

Jonathan Amsterdam f211cc8e4a internal/mcp: reorganize the tool API, keeping generics

CallToolParams.Arguments is any.

Clients can send whatever they want.

Tool authors who create their own ToolHandler (bypassing NewTool)
will receive the arguments as a map[string]any which has been
validated against the input schema.

Tool authors who call NewTool can choose the type that the arguments
unmarshal into.

There is no double-unmarshaling and no downcasting.

There is no way for tool authors to avoid the unmarshal, and no way to
avoid the validation unless the omit an input schema, which is probably
bad for LLMs. If tool authors want this optimization, we can provide
it later.

Change-Id: Ieb201e56c7fb8a23bb1a93b27e946630ec9e79ad
Reviewed-on: https://go-review.googlesource.com/c/tools/+/679595
TryBot-Bypass: Jonathan Amsterdam <jba@google.com>
Auto-Submit: Jonathan Amsterdam <jba@google.com>
Reviewed-by: Robert Findley <rfindley@google.com>

2025-06-10 04:57:48 -07:00

3.5 KiB

Raw Blame History

MCP SDK prototype

Installation
Quickstart
Design
Testing
Code of Conduct
License

The mcp package provides a software development kit (SDK) for writing clients and servers of the model context protocol. It is unstable, and will change in breaking ways in the future. As of writing, it is a prototype to explore the design space of client/server transport and binding.

Installation

The mcp package is currently internal and cannot be imported using go get.

Quickstart

Here's an example that creates a client that talks to an MCP server running as a sidecar process:

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-client", "v1.0.0", nil)
	// Connect to a server over stdin/stdout
	transport := mcp.NewCommandTransport(exec.Command("myserver"))
	session, err := client.Connect(ctx, transport)
	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"},
	}
	if res, err := session.CallTool(ctx, params); err != nil {
		log.Printf("CallTool failed: %v", err)
	} else {
		if res.IsError {
			log.Print("tool failed")
		}
		for _, c := range res.Content {
			log.Print(c.Text)
		}
	}
}

Here is an example of the corresponding server, connected over stdin/stdout:

package main

import (
	"context"

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

type HiParams struct {
	Name string `json:"name"`
}

func SayHi(ctx context.Context, cc *mcp.ServerSession, params *mcp.CallToolParamsFor[HiParams]) (*mcp.CallToolResultFor[string], error) {
	return &mcp.CallToolResultFor[string]{
		Content: []*mcp.Content{mcp.NewTextContent("Hi " + params.Name)},
	}, nil
}

func main() {
	// Create a server with a single tool.
	server := mcp.NewServer("greeter", "v1.0.0", nil)
	server.AddTools(mcp.NewTool("greet", "say hi", SayHi))
	// Run the server over stdin/stdout, until the client disconnects
	_ = server.Run(context.Background(), mcp.NewStdIOTransport())
}

Design

See design.md for the SDK design. That document is canonical: given any divergence between the design doc and this prototype, the doc reflects the latest design.

Testing

To test your client or server using stdio transport, you can use an in-memory transport. See example.

To test your client or server using sse transport, you can use the httptest package. See example.

Code of Conduct

This project follows the Go Community Code of Conduct. If you encounter a conduct-related issue, please mail conduct@golang.org.

License

Unless otherwise noted, the Go source files are distributed under the BSD-style license found in the LICENSE file.

Upon a potential move to the modelcontextprotocol organization, the license will be updated to the MIT License, and the license header will reflect the Go MCP SDK Authors.

3.5 KiB Raw Blame History