modelcontextprotocol/go-sdk
Watch
1
0
Fork
You've already forked go-sdk
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2
go-sdk/internal/docs/troubleshooting.src.md
Robert Findley ac2f175214
 docs: add feature and troubleshooting documentation (#463) 
Add a framework for feature documentation, and start populating it with
our SDK documentation.

This framework is as follows:
- internal/docs/**.src.md is the markdown source for the docs/
  directory.
- The x/example/internal/cmd/weave tool is used to compile these docs to
  the top-level docs, supporting both linked code samples and generated
  tables of contents.
- The readme-check workflow is updated to check these docs as well.
- The structure of these docs follows the MCP spec.
- Wherever possible, example code is linked from actual Go documentation
  examples, so that it is testable.

Some minor modifications to the weave tool were made to support this
framework.

Additionally, partially fill out this documentation with content on
base protocol and client features, as well as troubleshooting help.

Along the way, a bug was encountered that our LoggingTransport was not
concurrency safe. This is fixed with a mutex.

Fixes https://github.com/modelcontextprotocol/go-sdk/issues/466
Fixes https://github.com/modelcontextprotocol/go-sdk/issues/409
Updates https://github.com/modelcontextprotocol/go-sdk/issues/442
2025-09-16 11:13:40 -04:00

1.6 KiB
Raw Permalink Blame History

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:

%include ../../mcp/transport_example_test.go loggingtransport -

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:

%include ../../mcp/streamable_example_test.go httpmiddleware -

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