Troubleshooting

The Model Context Protocol is a complicated spec that leaves some room for interpretation. Client and server SDKs can behave differently, or can be more or less strict about their inputs. And of course, bugs happen.

When you encounter a problem using the Go SDK, these instructions can help collect information that will be useful in debugging. Please try to provide this information in a bug report, so that maintainers can more quickly understand what's going wrong.

And most of all, please do file bugs.

Using the MCP inspector

To debug an MCP server, you can use the MCP inspector. This is useful for testing your server and verifying that it works with the typescript SDK, as well as inspecting MCP traffic.

Collecting MCP logs

For stdio transport connections, you can also inspect MCP traffic using a LoggingTransport:

func ExampleLoggingTransport() {
    ctx := context.Background()
    t1, t2 := mcp.NewInMemoryTransports()
    server := mcp.NewServer(&mcp.Implementation{Name: "server", Version: "v0.0.1"}, nil)
    serverSession, err := server.Connect(ctx, t1, nil)
    if err != nil {
        log.Fatal(err)
    }
    defer serverSession.Close()

    client := mcp.NewClient(&mcp.Implementation{Name: "client", Version: "v0.0.1"}, nil)
    var b bytes.Buffer
    logTransport := &mcp.LoggingTransport{Transport: t2, Writer: &b}
    clientSession, err := client.Connect(ctx, logTransport, nil)
    if err != nil {
        log.Fatal(err)
    }
    defer clientSession.Close()

    // Sort for stability: reads are concurrent to writes.
    for _, line := range slices.Sorted(strings.SplitSeq(b.String(), "\n")) {
        fmt.Println(line)
    }

    // Output:
    // read: {"jsonrpc":"2.0","id":1,"result":{"capabilities":{"logging":{}},"protocolVersion":"2025-11-25","serverInfo":{"name":"server","version":"v0.0.1"}}}
    // write: {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"clientInfo":{"name":"client","version":"v0.0.1"},"protocolVersion":"2025-11-25","capabilities":{"roots":{"listChanged":true}}}}
    // write: {"jsonrpc":"2.0","method":"notifications/initialized","params":{}}
}

That example uses a bytes.Buffer, but you can also log to a file, or to os.Stderr.

Inspecting HTTP traffic

There are a couple different ways to investigate traffic to an HTTP transport (streamable or legacy SSE).

The first is to use an HTTP middleware:

func ExampleStreamableHTTPHandler_middleware() {
    server := mcp.NewServer(&mcp.Implementation{Name: "server", Version: "v0.1.0"}, nil)
    handler := mcp.NewStreamableHTTPHandler(func(r *http.Request) *mcp.Server {
        return server
    }, &mcp.StreamableHTTPOptions{Stateless: true})
    loggingHandler := http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
        // Example debugging; you could also capture the response.
        body, err := io.ReadAll(req.Body)
        if err != nil {
            log.Fatal(err)
        }
        req.Body.Close() // ignore error
        req.Body = io.NopCloser(bytes.NewBuffer(body))
        fmt.Println(req.Method, string(body))
        handler.ServeHTTP(w, req)
    })
    httpServer := httptest.NewServer(loggingHandler)
    defer httpServer.Close()

    // The SDK is currently permissive of some missing keys in "params".
    mustPostMessage(`{"jsonrpc": "2.0", "id": 1, "method":"initialize", "params": {}}`, httpServer.URL)
    // Output:
    // POST {"jsonrpc": "2.0", "id": 1, "method":"initialize", "params": {}}
}

The second is to use a general purpose tool to inspect http traffic, such as wireshark or tcpdump.