Merge branch 'main' into fgrosse/479-connection-closing-callback

Author: fgrosse

.github/workflows/docs-check.yml

@@ -0,0 +1,39 @@
+name: Docs Check
+on:
+  workflow_dispatch:
+  pull_request:
+    paths:
+      - 'internal/readme/**'
+      - 'README.md'
+      - 'internal/docs/**'
+      - 'docs/**'
+
+permissions:
+  contents: read
+
+jobs:
+  docs-check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Set up Go
+        uses: actions/setup-go@d35c59abb061a4a6fb18e82ac0862c26744d6ab5 # v5
+      - name: Check out code
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4
+      - name: Check docs are up-to-date
+        run: |
+          go generate ./...
+          if [ -n "$(git status --porcelain)" ]; then
+            echo "ERROR: docs are not up-to-date!"
+            echo ""
+            echo "The docs differ from what would be generated by `go generate ./...`."
+            echo "Please update internal/**/*.src.md instead of directly editing README.md or docs/ files,"
+            echo "then run `go generate ./...` to regenerate docs."
+            echo ""
+            echo "Changes:"
+            git status --porcelain
+            echo ""
+            echo "Diff:"
+            git diff
+            exit 1
+          fi
+          echo "Docs are up-to-date."

.github/workflows/readme-check.yml

@@ -14,9 +14,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Check out code
-        uses: actions/checkout@v4
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4
       - name: Set up Go
-        uses: actions/setup-go@v5
+        uses: actions/setup-go@d35c59abb061a4a6fb18e82ac0862c26744d6ab5 # v5
         with:
           go-version: "^1.23"
       - name: Check formatting
@@ -31,7 +31,7 @@ jobs:
       - name: Run Go vet
         run: go vet ./...
       - name: Run staticcheck
-        uses: dominikh/staticcheck-action@v1
+        uses: dominikh/staticcheck-action@024238d2898c874f26d723e7d0ff4308c35589a2 # v1
         with:
           version: "latest"
 
@@ -42,9 +42,9 @@ jobs:
         go: ["1.23", "1.24", "1.25"]
     steps:
       - name: Check out code
-        uses: actions/checkout@v4
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4
       - name: Set up Go
-        uses: actions/setup-go@v5
+        uses: actions/setup-go@d35c59abb061a4a6fb18e82ac0862c26744d6ab5 # v5
         with:
           go-version: ${{ matrix.go }}
       - name: Test
@@ -54,9 +54,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Check out code
-        uses: actions/checkout@v4
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4
       - name: Set up Go
-        uses: actions/setup-go@v5
+        uses: actions/setup-go@d35c59abb061a4a6fb18e82ac0862c26744d6ab5 # v5
         with:
           go-version: "1.24"
       - name: Test with -race

.github/workflows/test.yml

@@ -13,7 +13,7 @@ The SDK supports this as follows:
 
 **Client-side**: The SDK client always has the `roots.listChanged` capability.
 To add roots to a client, use the
-[`Client.AddRoots`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#AddRoots)
+[`Client.AddRoots`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#Client.AddRoots)
 and
 [`Client.RemoveRoots`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#Client.RemoveRoots)
 methods. If any servers are already [connected](protocol.md#lifecycle) to the

docs/client.md

@@ -8,7 +8,12 @@
 	1. [Custom transports](#custom-transports)
 	1. [Concurrency](#concurrency)
 1. [Authorization](#authorization)
+	1. [Server](#server)
+	1. [Client](#client)
 1. [Security](#security)
+	1. [Confused Deputy](#confused-deputy)
+	1. [Token Passthrough](#token-passthrough)
+	1. [Session Hijacking](#session-hijacking)
 1. [Utilities](#utilities)
 	1. [Cancellation](#cancellation)
 	1. [Ping](#ping)
@@ -182,15 +187,35 @@ the server using the streamable transport protocol.
 
 #### Stateless Mode
 
-<!-- TODO -->
+The streamable server supports a _stateless mode_ by setting
+[`StreamableHTTPOptions.Stateless`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#StreamableHTTPOptions.Stateless),
+which is where the server does not perform any validation of the session id,
+and uses a temporary session to handle requests. In this mode, it is impossible
+for the server to make client requests, as there is no way for the client's
+response to reach the session.
 
-#### Sessionless mode
+However, it is still possible for the server to access the `ServerSession.ID`
+to see the logical session
 
-<!-- TODO -->
+> [!WARNING]
+> Stateless mode is not directly discussed in the spec, and is still being
+> defined. See modelcontextprotocol/modelcontextprotocol#1364,
+> modelcontextprotocol/modelcontextprotocol#1372, or
+> modelcontextprotocol/modelcontextprotocol#11442 for potential refinements.
+
+_See [examples/server/distributed](../examples/server/distributed/main.go) for
+an example using statless mode to implement a server distributed across
+multiple processes._
 
 ### Custom transports
 
-<!-- TODO -->
+The SDK supports [custom
+transports](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#custom-transports)
+by implementing the
+[`Transport`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#Transport)
+interface: a logical bidirectional stream of JSON-RPC messages.
+
+_Full example: [examples/server/custom-transport](../examples/server/custom-transport/main.go)._
 
 ### Concurrency
 
@@ -212,11 +237,67 @@ for more background.
 
 ## Authorization
 
-<!-- TODO -->
+### Server
+
+To write an MCP server that performs authorization,
+use [`RequireBearerToken`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/auth#RequireBearerToken).
+This function is middleware that wraps an HTTP handler, such as the one returned
+by [`NewStreamableHTTPHandler`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#NewStreamableHTTPHandler), to provide support for verifying bearer tokens.
+The middleware function checks every request for an Authorization header with a bearer token,
+and invokes the 
+[`TokenVerifier`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/auth#TokenVerifier)
+ passed to `RequireBearerToken` to parse the token and perform validation.
+The middleware function checks expiration and scopes (if they are provided in
+[`RequireBearerTokenOptions.Scopes`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/auth#RequireBearerTokenOptions.Scopes)), so the
+`TokenVerifer` doesn't have to.
+If [`RequireBearerTokenOptions.ResourceMetadataURL`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/auth#RequireBearerTokenOptions.ResourceMetadataURL) is set and verification fails, 
+the middleware function sets the WWW-Authenticate header as required by the [Protected Resource
+Metadata spec](https://datatracker.ietf.org/doc/html/rfc9728).
+
+The  [_auth middleware example_](https://github.com/modelcontextprotocol/go-sdk/tree/main/examples/server/auth-middleware) shows how to implement authorization for both JWT tokens and API keys.
+
+### Client
+
+Client-side OAuth is implemented by setting  
+[`StreamableClientTransport.HTTPClient`](https://pkg.go.dev/github.com/modelcontextprotocol/[email protected]/mcp#StreamableClientTransport.HTTPClient) to a custom [`http.Client`](https://pkg.go.dev/net/http#Client)
+Additional support is forthcoming; see #493.
 
 ## Security
 
-<!-- TODO -->
+Here we discuss the mitigations described under
+the MCP spec's [Security Best Practices](https://modelcontextprotocol.io/specification/2025-06-18/basic/security_best_practices) section, and how we handle them.
+
+### Confused Deputy
+
+The [mitigation](https://modelcontextprotocol.io/specification/2025-06-18/basic/security_best_practices#mitigation), obtaining user consent for dynamically registered clients,
+happens on the MCP client. At present we don't provide client-side OAuth support.
+
+
+### Token Passthrough
+
+The [mitigation](https://modelcontextprotocol.io/specification/2025-06-18/basic/security_best_practices#mitigation-2), accepting only tokens that were issued for the server, depends on the structure
+of tokens and is the responsibility of the
+[`TokenVerifier`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/auth#TokenVerifier)
+provided to 
+[`RequireBearerToken`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/auth#RequireBearerToken).
+
+### Session Hijacking
+
+The [mitigations](https://modelcontextprotocol.io/specification/2025-06-18/basic/security_best_practices#mitigation-3) are as follows:
+
+- _Verify all inbound requests_. The [`RequireBearerToken`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/auth#RequireBearerToken)
+middleware function will verify all HTTP requests that it receives. It is the
+user's responsibility to wrap that function around all handlers in their server.
+
+- _Secure session IDs_. This SDK generates cryptographically secure session IDs by default.
+If you create your own with 
+[`ServerOptions.GetSessionID`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ServerOptions.GetSessionID), it is your responsibility to ensure they are secure.
+If you are using Go 1.24 or above,
+we recommend using [`crypto/rand.Text`](https://pkg.go.dev/crypto/rand#Text) 
+
+- _Binding session IDs to user information_. This is an application requirement, out of scope
+for the SDK. You can create your own session IDs by setting
+[`ServerOptions.GetSessionID`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ServerOptions.GetSessionID).
 
 ## Utilities