You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/client.md
+6-13Lines changed: 6 additions & 13 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,6 @@
1
1
## Client overview
2
2
3
-
The SDK provides a high-level `Client` class that connects to MCP servers over
4
-
different transports:
3
+
The SDK provides a high-level `Client` class that connects to MCP servers over different transports:
5
4
6
5
-`StdioClientTransport` – for local processes you spawn.
7
6
-`StreamableHTTPClientTransport` – for remote HTTP servers.
@@ -22,18 +21,15 @@ A typical flow:
22
21
1. Construct a `Client` with name, version and capabilities.
23
22
2. Create a transport and call `client.connect(transport)`.
24
23
3. Use high-level helpers:
25
-
-`listTools`, `callTool`
26
-
-`listPrompts`, `getPrompt`
27
-
-`listResources`, `readResource`
24
+
-`listTools`, `callTool`
25
+
-`listPrompts`, `getPrompt`
26
+
-`listResources`, `readResource`
28
27
29
-
See `src/examples/client/simpleStreamableHttp.ts` for an interactive CLI client
30
-
that exercises these methods and shows how to handle notifications, elicitation
31
-
and tasks.
28
+
See `src/examples/client/simpleStreamableHttp.ts` for an interactive CLI client that exercises these methods and shows how to handle notifications, elicitation and tasks.
32
29
33
30
## Transports and backwards compatibility
34
31
35
-
To support both modern Streamable HTTP and legacy SSE servers, use a client
36
-
that:
32
+
To support both modern Streamable HTTP and legacy SSE servers, use a client that:
37
33
38
34
1. Tries `StreamableHTTPClientTransport`.
39
35
2. Falls back to `SSEClientTransport` on a 4xx response.
@@ -62,6 +58,3 @@ These examples show how to:
62
58
- Perform dynamic client registration if needed.
63
59
- Acquire access tokens.
64
60
- Attach OAuth credentials to Streamable HTTP requests.
Copy file name to clipboardExpand all lines: docs/faq.md
+10-9Lines changed: 10 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -15,25 +15,27 @@
15
15
16
16
This TypeScript error can appear when upgrading to newer SDK versions that support Zod v4 (for example, from `@modelcontextprotocol/sdk``1.22.0` to `1.23.0`) **and** your project ends up with multiple `zod` versions in the dependency tree.
17
17
18
-
When there are multiple copies or versions of `zod`, TypeScript may try to instantiate very complex, cross-version types and hit its recursion limits, resulting in `TS2589`. This scenario is discussed in GitHub issue [#1180](https://github.com/modelcontextprotocol/typescript-sdk/issues/1180#event-21236550401).
18
+
When there are multiple copies or versions of `zod`, TypeScript may try to instantiate very complex, cross-version types and hit its recursion limits, resulting in `TS2589`. This scenario is discussed in GitHub issue
- Run `npm ls zod` or `npm explain zod`, `pnpm list zod` or `pnpm why zod`, or `yarn why zod` and check whether more than one version is installed.
24
+
- Run `npm ls zod` or `npm explain zod`, `pnpm list zod` or `pnpm why zod`, or `yarn why zod` and check whether more than one version is installed.
24
25
-**Align on a single `zod` version**:
25
-
- Make sure all packages that depend on `zod` use a compatible version range so that your package manager can hoist a single copy.
26
-
- In monorepos, consider declaring `zod` at the workspace root and using compatible ranges in individual packages.
26
+
- Make sure all packages that depend on `zod` use a compatible version range so that your package manager can hoist a single copy.
27
+
- In monorepos, consider declaring `zod` at the workspace root and using compatible ranges in individual packages.
27
28
-**Use overrides/resolutions if necessary**:
28
-
- With npm, Yarn, or pnpm, you can use `overrides` / `resolutions` to force a single `zod` version if some transitive dependencies pull in a different one.
29
+
- With npm, Yarn, or pnpm, you can use `overrides` / `resolutions` to force a single `zod` version if some transitive dependencies pull in a different one.
29
30
30
31
Once your project is using a single, compatible `zod` version, the `TS2589` error should no longer occur.
31
32
32
33
## Clients
33
34
34
35
### How do I enable Web Crypto (`globalThis.crypto`) for client authentication in older Node.js versions?
35
36
36
-
The SDK’s OAuth client authentication helpers (for example, those in `src/client/auth-extensions.ts` that use `jose`) rely on the Web Crypto API exposed as `globalThis.crypto`. This is especially important for **client credentials** and **JWT-based** authentication flows used by MCP clients.
37
+
The SDK’s OAuth client authentication helpers (for example, those in `src/client/auth-extensions.ts` that use `jose`) rely on the Web Crypto API exposed as `globalThis.crypto`. This is especially important for **client credentials** and **JWT-based** authentication flows used by
38
+
MCP clients.
37
39
38
40
-**Node.js v19.0.0 and later**: `globalThis.crypto` is available by default.
39
41
-**Node.js v18.x**: `globalThis.crypto` may not be defined by default. In this repository we polyfill it for tests (see `vitest.setup.ts`), and you should do the same in your app if it is missing – or alternatively, run Node with `--experimental-global-webcrypto` as per your
@@ -59,6 +61,5 @@ For production use, you can either:
59
61
60
62
### Where can I find runnable server examples?
61
63
62
-
The SDK ships several runnable server examples under `src/examples/server`. The root `README.md` contains a curated **Server examples** table that links to each scenario (stateful/stateless Streamable HTTP, JSON-only mode, SSE/backwards compatibility, elicitation, sampling, tasks, and OAuth demos), and `src/examples/README.md` includes commands and deployment diagrams for running them.
63
-
64
-
64
+
The SDK ships several runnable server examples under `src/examples/server`. The root `README.md` contains a curated **Server examples** table that links to each scenario (stateful/stateless Streamable HTTP, JSON-only mode, SSE/backwards compatibility, elicitation, sampling,
65
+
tasks, and OAuth demos), and `src/examples/README.md` includes commands and deployment diagrams for running them.
MCP servers can request LLM completions from connected clients that support the
4
-
sampling capability. This lets your tools offload summarisation or generation
5
-
to the client’s model.
3
+
MCP servers can request LLM completions from connected clients that support the sampling capability. This lets your tools offload summarisation or generation to the client’s model.
6
4
7
5
For a runnable server that combines tools, logging and tasks, see:
8
6
@@ -18,24 +16,18 @@ Refer to the MCP spec’s sampling section for full request/response details.
18
16
19
17
## Form elicitation
20
18
21
-
Form elicitation lets a tool ask the user for additional, **non‑sensitive**
22
-
information via a schema‑driven form. The server sends a schema and message,
23
-
and the client is responsible for collecting and returning the data.
19
+
Form elicitation lets a tool ask the user for additional, **non‑sensitive** information via a schema‑driven form. The server sends a schema and message, and the client is responsible for collecting and returning the data.
The `simpleStreamableHttp` server also includes a `collect-user-info` tool that
31
-
demonstrates how to drive elicitation from a tool and handle the response.
26
+
The `simpleStreamableHttp` server also includes a `collect-user-info` tool that demonstrates how to drive elicitation from a tool and handle the response.
32
27
33
28
## URL elicitation
34
29
35
-
URL elicitation is designed for sensitive data and secure web‑based flows
36
-
(e.g., collecting an API key, confirming a payment, or doing third‑party OAuth).
37
-
Instead of returning form data, the server asks the client to open a URL and
38
-
the rest of the flow happens in the browser.
30
+
URL elicitation is designed for sensitive data and secure web‑based flows (e.g., collecting an API key, confirming a payment, or doing third‑party OAuth). Instead of returning form data, the server asks the client to open a URL and the rest of the flow happens in the browser.
39
31
40
32
Runnable example:
41
33
@@ -46,12 +38,8 @@ Key points:
46
38
47
39
- Use `mode: 'url'` when calling `server.server.elicitInput(...)`.
48
40
- Implement a client‑side handler for `ElicitRequestSchema` that:
49
-
- Shows the full URL and reason to the user.
50
-
- Asks for explicit consent.
51
-
- Opens the URL in the system browser.
52
-
53
-
Sensitive information **must not** be collected via form elicitation; always
54
-
use URL elicitation or out‑of‑band flows for secrets.
55
-
56
-
41
+
- Shows the full URL and reason to the user.
42
+
- Asks for explicit consent.
43
+
- Opens the URL in the system browser.
57
44
45
+
Sensitive information **must not** be collected via form elicitation; always use URL elicitation or out‑of‑band flows for secrets.
Copy file name to clipboardExpand all lines: docs/server.md
+7-16Lines changed: 7 additions & 16 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,8 +1,6 @@
1
1
## Server overview
2
2
3
-
This SDK lets you build MCP servers in TypeScript and connect them to different transports.
4
-
For most use cases you will use `McpServer` from `@modelcontextprotocol/sdk/server/mcp.js`
5
-
and choose one of:
3
+
This SDK lets you build MCP servers in TypeScript and connect them to different transports. For most use cases you will use `McpServer` from `@modelcontextprotocol/sdk/server/mcp.js` and choose one of:
6
4
7
5
-**Streamable HTTP** (recommended for remote servers)
8
6
-**HTTP + SSE** (deprecated, for backwards compatibility only)
@@ -50,8 +48,7 @@ Examples:
50
48
51
49
### Deprecated HTTP + SSE
52
50
53
-
The older HTTP+SSE transport (protocol version 2024‑11‑05) is supported only for
54
-
backwards compatibility. New implementations should prefer Streamable HTTP.
51
+
The older HTTP+SSE transport (protocol version 2024‑11‑05) is supported only for backwards compatibility. New implementations should prefer Streamable HTTP.
55
52
56
53
Examples:
57
54
@@ -67,31 +64,25 @@ For a minimal “getting started” experience:
67
64
2. Remove features you do not need (tasks, advanced logging, OAuth, etc.).
68
65
3. Register your own tools, resources and prompts.
69
66
70
-
For more detailed patterns (stateless vs stateful, JSON response mode, CORS, DNS
71
-
rebind protection), see the examples above and the MCP spec sections on transports.
67
+
For more detailed patterns (stateless vs stateful, JSON response mode, CORS, DNS rebind protection), see the examples above and the MCP spec sections on transports.
72
68
73
69
## Multi‑node deployment patterns
74
70
75
-
The SDK supports multi‑node deployments using Streamable HTTP. The high‑level
76
-
patterns are documented in `src/examples/README.md`:
71
+
The SDK supports multi‑node deployments using Streamable HTTP. The high‑level patterns are documented in `src/examples/README.md`:
77
72
78
73
- Stateless mode (any node can handle any request)
79
74
- Persistent storage mode (shared database for session state)
80
75
- Local state with message routing (message queue + pub/sub)
81
76
82
-
Those deployment diagrams are kept in `src/examples/README.md` so the examples
83
-
and documentation stay aligned.
77
+
Those deployment diagrams are kept in `src/examples/README.md` so the examples and documentation stay aligned.
Task-based execution enables “call-now, fetch-later” patterns for long-running
4
-
operations. Instead of returning a result immediately, a tool creates a task
5
-
that can be polled or resumed later.
3
+
Task-based execution enables “call-now, fetch-later” patterns for long-running operations. Instead of returning a result immediately, a tool creates a task that can be polled or resumed later.
6
4
7
-
The APIs live under the experimental `.experimental.tasks` namespace and may
8
-
change without notice.
5
+
The APIs live under the experimental `.experimental.tasks` namespace and may change without notice.
9
6
10
7
### Server-side concepts
11
8
@@ -24,20 +21,13 @@ For a runnable example that uses the in-memory store shipped with the SDK, see:
24
21
25
22
On the client, you use:
26
23
27
-
-`client.experimental.tasks.callToolStream(...)` to start a tool call that may
28
-
create a task and emit status updates over time.
29
-
-`client.getTask(...)` and `client.getTaskResult(...)` to check status and
30
-
fetch results after reconnecting.
24
+
-`client.experimental.tasks.callToolStream(...)` to start a tool call that may create a task and emit status updates over time.
25
+
-`client.getTask(...)` and `client.getTaskResult(...)` to check status and fetch results after reconnecting.
31
26
32
27
The interactive client in:
33
28
34
29
-`src/examples/client/simpleStreamableHttp.ts`
35
30
36
-
includes commands to demonstrate calling tools that support tasks and handling
37
-
their lifecycle.
38
-
39
-
See the MCP spec’s tasks section and the example server/client above for a full
40
-
walkthrough of the task status lifecycle and TTL handling.
41
-
42
-
31
+
includes commands to demonstrate calling tools that support tasks and handling their lifecycle.
43
32
33
+
See the MCP spec’s tasks section and the example server/client above for a full walkthrough of the task status lifecycle and TTL handling.
Copy file name to clipboardExpand all lines: docs/tools-resources-prompts.md
+9-24Lines changed: 9 additions & 24 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,6 @@
1
1
## Tools
2
2
3
-
Tools let MCP clients ask your server to take actions. They are usually the
4
-
main way that LLMs call into your application.
3
+
Tools let MCP clients ask your server to take actions. They are usually the main way that LLMs call into your application.
5
4
6
5
A typical registration with `registerTool` looks like this:
7
6
@@ -34,17 +33,13 @@ This snippet is illustrative only; for runnable servers that expose tools, see:
34
33
35
34
### ResourceLink outputs
36
35
37
-
Tools can return `resource_link` content items to reference large resources
38
-
without embedding them directly, allowing clients to fetch only what they need.
36
+
Tools can return `resource_link` content items to reference large resources without embedding them directly, allowing clients to fetch only what they need.
39
37
40
-
The README’s `list-files` example shows the pattern conceptually; for concrete
41
-
usage, see the Streamable HTTP examples in `src/examples/server`.
38
+
The README’s `list-files` example shows the pattern conceptually; for concrete usage, see the Streamable HTTP examples in `src/examples/server`.
42
39
43
40
## Resources
44
41
45
-
Resources expose data to clients, but should not perform heavy computation or
46
-
side‑effects. They are ideal for configuration, documents, or other reference
47
-
data.
42
+
Resources expose data to clients, but should not perform heavy computation or side‑effects. They are ideal for configuration, documents, or other reference data.
48
43
49
44
Conceptually, you might register resources like:
50
45
@@ -63,15 +58,13 @@ server.registerResource(
63
58
);
64
59
```
65
60
66
-
Dynamic resources use `ResourceTemplate` and can support completions on path
67
-
parameters. For full runnable examples of resources:
61
+
Dynamic resources use `ResourceTemplate` and can support completions on path parameters. For full runnable examples of resources:
68
62
69
63
-`src/examples/server/simpleStreamableHttp.ts`
70
64
71
65
## Prompts
72
66
73
-
Prompts are reusable templates that help humans (or client UIs) talk to models
74
-
in a consistent way. They are declared on the server and listed through MCP.
67
+
Prompts are reusable templates that help humans (or client UIs) talk to models in a consistent way. They are declared on the server and listed through MCP.
75
68
76
69
A minimal prompt:
77
70
@@ -103,20 +96,12 @@ For prompts integrated into a full server, see:
103
96
104
97
## Completions
105
98
106
-
Both prompts and resources can support argument completions. On the client
107
-
side, you use `client.complete()` with a reference to the prompt or resource
108
-
and the partially‑typed argument.
99
+
Both prompts and resources can support argument completions. On the client side, you use `client.complete()` with a reference to the prompt or resource and the partially‑typed argument.
109
100
110
-
See the MCP spec sections on prompts and resources for complete details, and
111
-
`src/examples/client/simpleStreamableHttp.ts` for client‑side usage patterns.
101
+
See the MCP spec sections on prompts and resources for complete details, and `src/examples/client/simpleStreamableHttp.ts` for client‑side usage patterns.
112
102
113
103
## Display names and metadata
114
104
115
-
Tools, resources and prompts support a `title` field for human‑readable names.
116
-
Older APIs can also attach `annotations.title`. To compute the correct display
117
-
name on the client, use:
105
+
Tools, resources and prompts support a `title` field for human‑readable names. Older APIs can also attach `annotations.title`. To compute the correct display name on the client, use:
118
106
119
107
-`getDisplayName` from `@modelcontextprotocol/sdk/shared/metadataUtils.js`
Copy file name to clipboardExpand all lines: src/examples/README.md
+1-2Lines changed: 1 addition & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,6 @@
1
1
# MCP TypeScript SDK Examples
2
2
3
-
This directory contains example implementations of MCP clients and servers using the TypeScript SDK.
4
-
For a high-level index of scenarios and where they live, see the **Examples** table in the root `README.md`.
3
+
This directory contains example implementations of MCP clients and servers using the TypeScript SDK. For a high-level index of scenarios and where they live, see the **Examples** table in the root `README.md`.
0 commit comments