Skip to content

Commit a1d6ed4

Browse files
findleyrfindleyr
committed
add lifecycle documentation
1 parent c95a732 commit a1d6ed4

File tree

11 files changed

+262
-20
lines changed

11 files changed

+262
-20
lines changed

‎docs/client.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ method. To receive notifications about root changes, set
2626
[`ServerOptions.RootsListChangedHandler`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ServerOptions.RootsListChangedHandler).
2727

2828
```go
29-
func ExampleClient_AddRoots() {
29+
func Example_roots() {
3030
ctx := context.Background()
3131

3232
// Create a client with a single root.
@@ -81,7 +81,7 @@ This function is invoked whenever the server requests sampling.
8181
[`ServerSession.CreateMessage`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ServerSession.CreateMessage).
8282

8383
```go
84-
func ExampleClientOptions_CreateMessageHandler() {
84+
func Example_sampling() {
8585
ctx := context.Background()
8686

8787
// Create a client with a single root.
@@ -133,7 +133,7 @@ otherwise, elicitation returns an error.
133133
// go get golang.org/x/example/docs/../../mcp
134134

135135
```go
136-
func ExampleClientOptions_ElicitationHandler() {
136+
func Example_elicitation() {
137137
ctx := context.Background()
138138
ct, st := mcp.NewInMemoryTransports()
139139

‎docs/protocol.md‎

Lines changed: 100 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,13 +9,101 @@
99

1010
## Lifecycle
1111

12+
The SDK provides an API for defining both MCP clients and servers, and
13+
connecting them over various transports. When a client and server are
14+
connected, it creates a logical session, which follows the MCP spec's
15+
[lifecycle](https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle).
16+
17+
In this SDK, both a
18+
[`Client`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#Client)
19+
and
20+
[`Server`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#Server)
21+
can handle multiple peers. Every time a new peer is connected, it creates a new
22+
session.
23+
24+
- A `Client` is a logical MCP client, configured with various
25+
[`ClientOptions`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ClientOptions).
26+
- When a client is connected to a server using
27+
[`Client.Connect`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#Client.Connect),
28+
it creates a
29+
[`ClientSession`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ClientSession).
30+
This session is initialized during the `Connect` method, and provides methods
31+
to communicate with the server peer.
32+
- A `Server` is a logical MCP server, configure with various
33+
[`ServerOptions`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ServerOptions).
34+
- When a server is connected to a client using
35+
[`Server.Connect`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#Server.Connect),
36+
it creates a
37+
[`ServerSession`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ServerSession).
38+
This session is not initialized until the client sends the
39+
`notifications/initialized` message. Use `ServerOptions.InitializedHandler`
40+
to listen for this event, or just use the session through various feature
41+
handlers (such as a `ToolHandler`). Requests to the server are rejected until
42+
the client has initialized the session.
43+
44+
Both `ClientSession` and `ServerSession` have a `Close` method to terminate the
45+
session, and a `Wait` method to await session termination by the peer. Typically,
46+
it is the client's responsibility to end the session.
47+
48+
```go
49+
func Example_lifeCycle() {
50+
ctx := context.Background()
51+
52+
// Create a client and server.
53+
// Wait for the client to initialize the session.
54+
client := mcp.NewClient(&mcp.Implementation{Name: "client", Version: "v0.0.1"}, nil)
55+
server := mcp.NewServer(&mcp.Implementation{Name: "server", Version: "v0.0.1"}, &mcp.ServerOptions{
56+
InitializedHandler: func(context.Context, *mcp.InitializedRequest) {
57+
fmt.Println("initialized!")
58+
},
59+
})
60+
61+
// Connect the server and client using in-memory transports.
62+
//
63+
// Connect the server first so that it's ready to receive initialization
64+
// messages from the client.
65+
t1, t2 := mcp.NewInMemoryTransports()
66+
serverSession, err := server.Connect(ctx, t1, nil)
67+
if err != nil {
68+
log.Fatal(err)
69+
}
70+
clientSession, err := client.Connect(ctx, t2, nil)
71+
if err != nil {
72+
log.Fatal(err)
73+
}
74+
75+
// Now shut down the session by closing the client, and waiting for the
76+
// server session to end.
77+
if err := clientSession.Close(); err != nil {
78+
log.Fatal(err)
79+
}
80+
if err := serverSession.Wait(); err != nil {
81+
log.Fatal(err)
82+
}
83+
// Output: initialized!
84+
}
85+
```
86+
1287
## Transports
1388

89+
A
90+
[`Transport`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#Transport)
91+
is used to connect a client or server to a peer. Specifically, it's something
92+
that can create a (logical) bidirectional stream of JSON-RPC messages. Most
93+
transport implementations described below are specific to either the client or
94+
server: a "client transport" is something that can be used to connect a client
95+
to a server, and a "server transport" is something that can be used to connect
96+
a server to a client. However, it's possible for a transport to be both a
97+
client and server transport, such as the `InMemoryTransport` used in the
98+
lifecycle example above.
99+
14100
Transports should not be reused for multiple connections: if you need to create
15101
multiple connections, use different transports.
16102

17103
### Stdio Transport
18104

105+
<!-- TODO -->
106+
19107
### Streamable Transport
20108

21109
The [streamable
@@ -72,10 +160,16 @@ the server using the streamable transport protocol.
72160

73161
#### Stateless Mode
74162

163+
<!-- TODO -->
164+
75165
#### Sessionless mode
76166

167+
<!-- TODO -->
168+
77169
### Custom transports
78170

171+
<!-- TODO -->
172+
79173
### Concurrency
80174

81175
In general, MCP offers no guarantees about concurrency semantics: if a client
@@ -95,11 +189,11 @@ for more background.
95189

96190
## Authorization
97191

98-
**TODO**
192+
<!-- TODO -->
99193

100194
## Security
101195

102-
**TODO**
196+
<!-- TODO -->
103197

104198
## Utilities
105199

@@ -121,4 +215,8 @@ server has observed it (see [concurrency](#concurrency)).
121215

122216
### Ping
123217

218+
<!-- TODO -->
219+
124220
### Progress
221+
222+
<!-- TODO -->

‎docs/server.md‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,16 +8,28 @@
88

99
## Prompts
1010

11+
<!-- TODO -->
12+
1113
## Resources
1214

15+
<!-- TODO -->
16+
1317
## Tools
1418

15-
Tools are a big topic! See [tools.md](tools.md) for details.
19+
<!-- TODO -->
1620

1721
## Utilities
1822

23+
<!-- TODO -->
24+
1925
### Completion
2026

27+
<!-- TODO -->
28+
2129
### Logging
2230

31+
<!-- TODO -->
32+
2333
### Pagination
34+
35+
<!-- TODO -->

‎internal/docs/client.src.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ client, a call to `AddRoot` or `RemoveRoots` will result in a
2222
method. To receive notifications about root changes, set
2323
[`ServerOptions.RootsListChangedHandler`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ServerOptions.RootsListChangedHandler).
2424

25-
%include ../../mcp/client_example_test.go addroots -
25+
%include ../../mcp/client_example_test.go roots -
2626

2727
## Sampling
2828

@@ -37,7 +37,7 @@ This function is invoked whenever the server requests sampling.
3737
**Server-side**: To use sampling from the server, call
3838
[`ServerSession.CreateMessage`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ServerSession.CreateMessage).
3939

40-
%include ../../mcp/client_example_test.go createmessage -
40+
%include ../../mcp/client_example_test.go sampling -
4141

4242
## Elicitation
4343

‎internal/docs/protocol.src.md‎

Lines changed: 63 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,13 +4,64 @@
44

55
## Lifecycle
66

7+
The SDK provides an API for defining both MCP clients and servers, and
8+
connecting them over various transports. When a client and server are
9+
connected, it creates a logical session, which follows the MCP spec's
10+
[lifecycle](https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle).
11+
12+
In this SDK, both a
13+
[`Client`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#Client)
14+
and
15+
[`Server`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#Server)
16+
can handle multiple peers. Every time a new peer is connected, it creates a new
17+
session.
18+
19+
- A `Client` is a logical MCP client, configured with various
20+
[`ClientOptions`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ClientOptions).
21+
- When a client is connected to a server using
22+
[`Client.Connect`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#Client.Connect),
23+
it creates a
24+
[`ClientSession`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ClientSession).
25+
This session is initialized during the `Connect` method, and provides methods
26+
to communicate with the server peer.
27+
- A `Server` is a logical MCP server, configure with various
28+
[`ServerOptions`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ServerOptions).
29+
- When a server is connected to a client using
30+
[`Server.Connect`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#Server.Connect),
31+
it creates a
32+
[`ServerSession`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ServerSession).
33+
This session is not initialized until the client sends the
34+
`notifications/initialized` message. Use `ServerOptions.InitializedHandler`
35+
to listen for this event, or just use the session through various feature
36+
handlers (such as a `ToolHandler`). Requests to the server are rejected until
37+
the client has initialized the session.
38+
39+
Both `ClientSession` and `ServerSession` have a `Close` method to terminate the
40+
session, and a `Wait` method to await session termination by the peer. Typically,
41+
it is the client's responsibility to end the session.
42+
43+
%include ../../mcp/mcp_example_test.go lifecycle -
44+
745
## Transports
846

47+
A
48+
[`Transport`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#Transport)
49+
is used to connect a client or server to a peer. Specifically, it's something
50+
that can create a (logical) bidirectional stream of JSON-RPC messages. Most
51+
transport implementations described below are specific to either the client or
52+
server: a "client transport" is something that can be used to connect a client
53+
to a server, and a "server transport" is something that can be used to connect
54+
a server to a client. However, it's possible for a transport to be both a
55+
client and server transport, such as the `InMemoryTransport` used in the
56+
lifecycle example above.
57+
958
Transports should not be reused for multiple connections: if you need to create
1059
multiple connections, use different transports.
1160

1261
### Stdio Transport
1362

63+
<!-- TODO -->
64+
1465
### Streamable Transport
1566

1667
The [streamable
@@ -48,10 +99,16 @@ the server using the streamable transport protocol.
4899

49100
#### Stateless Mode
50101

102+
<!-- TODO -->
103+
51104
#### Sessionless mode
52105

106+
<!-- TODO -->
107+
53108
### Custom transports
54109

110+
<!-- TODO -->
111+
55112
### Concurrency
56113

57114
In general, MCP offers no guarantees about concurrency semantics: if a client
@@ -71,11 +128,11 @@ for more background.
71128

72129
## Authorization
73130

74-
**TODO**
131+
<!-- TODO -->
75132

76133
## Security
77134

78-
**TODO**
135+
<!-- TODO -->
79136

80137
## Utilities
81138

@@ -97,4 +154,8 @@ server has observed it (see [concurrency](#concurrency)).
97154

98155
### Ping
99156

157+
<!-- TODO -->
158+
100159
### Progress
160+
161+
<!-- TODO -->

‎internal/docs/server.src.md‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,16 +4,28 @@
44

55
## Prompts
66

7+
<!-- TODO -->
8+
79
## Resources
810

11+
<!-- TODO -->
12+
913
## Tools
1014

11-
Tools are a big topic! See [tools.md](tools.md) for details.
15+
<!-- TODO -->
1216

1317
## Utilities
1418

19+
<!-- TODO -->
20+
1521
### Completion
1622

23+
<!-- TODO -->
24+
1725
### Logging
1826

27+
<!-- TODO -->
28+
1929
### Pagination
30+
31+
<!-- TODO -->

‎mcp/client.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -127,7 +127,7 @@ func (c *Client) capabilities() *ClientCapabilities {
127127
}
128128

129129
// Connect begins an MCP session by connecting to a server over the given
130-
// transport, and initializing the session.
130+
// transport. The resulting session is initialized, and ready to use.
131131
//
132132
// Typically, it is the responsibility of the client to close the connection
133133
// when it is no longer needed. However, if the connection is closed by the

0 commit comments

Comments
 (0)