rust-mcp-sdk 0.10.0

An asynchronous SDK and framework for building MCP-Servers and MCP-Clients, leveraging the rust-mcp-schema for type safe MCP Schema Objects.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292

# Rust MCP SDK - Examples

This folder contains a variety of example programs demonstrating how to use the rust-mcp-sdk crate to build MCP clients and MCP servers. The examples cover different transports (stdio, streamable HTTP/SSE) and variations (handler vs. core handler implementations).

## List of Examples
- **MCP Server**
    -  **[stdio examples](#%EF%B8%8F-mcp-server-examples-stdio)**
        - quick-start-server-stdio
        -  hello-world-mcp-server-stdio
        -  hello-world-mcp-server-stdio-core
    - **[Streamable HTTP Examples](#%EF%B8%8F-mcp-servers-examples-streamable-http)**
        - quick-start-streamable-http
        - hello-world-server-streamable-http
        - hello-world-server-streamable-http-core      
        - streamable_http_healthcheck  
    - **[Oauth Example](#%EF%B8%8F-mcp-server---oauth-example)**
        - mcp-server-oauth-remote
- **MCP Client**
    -  **[stdio examples](#%EF%B8%8F-mcp-client-examples-stdio)**
        - quick-start-client-stdio
        - simple-mcp-client-stdio
        - simple-mcp-client-stdio-core
    - **[Streamable HTTP Examples](#%EF%B8%8F-mcp-client-examples-streamable-http)**      
        - simple-mcp-client-streamable-http
        - simple-mcp-client-streamable-http-core
    - **[sse Examples](#%EF%B8%8F-mcp-client-examples-sse)**
        - simple-mcp-client-sse
        - simple-mcp-client-sse-core 
    - **[Oauth Example](#%EF%B8%8F-mcp-client---oauth-example)**
        - mcp-client-with-oauth

-----


### ➡️ MCP Server Examples (stdio)
Basic MCP server implementation using *stdio* transport, featuring two custom tools: `Say Hello` and `Say Goodbye`.
`hello-world-mcp-server-stdio` and `hello-world-mcp-server-stdio-core` also provides two static resource and a resource template that returns a Pokemon sprite as a blob resource.

- [quick-start-server-stdio.rs](quick-start-server-stdio.rs)
- [hello-world-mcp-server-stdio.rs](hello-world-mcp-server-stdio.rs)
- [hello-world-mcp-server-stdio-core.rs](hello-world-mcp-server-stdio-core.rs)

**Build the server:**
_for instance, build the `hello-world-mcp-server-stdio`_
```sh
cargo build --example hello-world-mcp-server-stdio # or quick_start_server_stdio or hello-world-mcp-server-stdio-core
```
The compiled binary will be located at `target/debug/examples/`

**Testing:**
You can use this binary with any MCP-compatible client. For easy testing and inspection, launch it in the [MCP Inspector](https://github.com/modelcontextprotocol/inspector), by selecting `stdio` transport , pointing it to the generated binary and connecting to the server.  

Here you can see it in action :
<img src="../assets/examples/hello-world-mcp-server.gif" alt="hello-world-mcp-server" width="800" />

-----

### ➡️ MCP Servers Examples (Streamable HTTP)
Minimal quick-start example demonstrating the fastest way to set up a basic MCP server using the **Streamable HTTP** transport and **SSE** for backward compatibility.

- [quick-start-streamable-http.rs](quick-start-streamable-http.rs)
- [hello-world-server-streamable-http.rs](hello-world-server-streamable-http.rs)
- [hello-world-server-streamable-http-core.rs](hello-world-server-streamable-http-core.rs)
- [streamable_http_healthcheck.rs](streamable_http_healthcheck.rs)

**Start the server:**
_for instance, start the `hello-world-server-streamable-http`_
```sh
cargo run --example hello-world-server-streamable-http
```

Once the server starts, you’ll see the following output in the terminal:
```sh
• Streamable HTTP Server is available at http://127.0.0.1:8080/mcp
• SSE Server is available at http://127.0.0.1:8080/sse
```


For easy testing and inspection, connect to it using [MCP Inspector](https://github.com/modelcontextprotocol/inspector).
start the inspector by running:

```bash
npx -y @modelcontextprotocol/inspector@latest
```

That will open the inspector in a browser,

Then , to test the server, visit one of the following URLs based on the desired transport:

* Streamable HTTP:
  [http://localhost:6274/?transport=streamable-http\&serverUrl=http://localhost:8080/mcp](http://localhost:6274/?transport=streamable-http&serverUrl=http://localhost:8080/mcp)
* SSE:
  [http://localhost:6274/?transport=sse\&serverUrl=http://localhost:8080/sse](http://localhost:6274/?transport=sse&serverUrl=http://localhost:8080/sse)

Here you can see it in action :

<img src="../assets/examples/hello-world-server-streamable-http.gif" alt="hello-world-mcp-server-streamable-http" width="800" />

-----


### ➡️ MCP Server - Oauth Example

- [mcp-server-oauth-remote.rs](mcp-server-oauth-remote.rs)

A minimal, MCP server example that demonstrates **OAuth 2.0 / OpenID Connect authentication** using the  `RemoteAuthProvider` from [rust-mcp-sdk](https://github.com/rust-mcp-stack/rust-mcp-sdk).

It features:
- Full OAuth 2.0 protection via bearer tokens
- Remote authentication metadata discovery
- Token verification using both JWKs and token introspection
- A single tool: `show_auth_info` - returns the authenticated user's claims and scopes in pretty-printed JSON

#### Overview

**RemoteAuthProvider** can be used with any OpenID Connect provider that supports Dynamic Client Registration (DCR), but in this example, it is configured to point to a local [Keycloak](https://www.keycloak.org) instance.

👉 For more information on how to start and configure your local Keycloak server, please refer to the  **keycloak-setup** section of the following blog post: https://modelcontextprotocol.io/docs/tutorials/security/authorization#keycloak-setup


#### Step 1:
Make sure you have a Keycloak server running and configured as described in this [blog post](https://modelcontextprotocol.io/docs/tutorials/security/authorization#keycloak-setup)

> 💡 _You can update the configuration in `create_oauth_provider()` function to connect to any other OAuth provider with DCR support or in case your keycloak configuration is different._

#### Step 2:
Set the `OAUTH_CLIENT_ID` and `OAUTH_CLIENT_SECRET` environment variables with the values from your keycloak server dashboard:

```
export OAUTH_CLIENT_ID=test-server OAUTH_CLIENT_SECRET=XYZ
```

#### Step 3:
start the server

```bash
cargo run --example mcp-server-oauth-remote
```

You will see:

```sh
• Streamable HTTP Server is available at http://[::1]:3000/
```

Now you can connect to it with [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector), or alternatively, use it with any MCP client you prefer.

```bash
npx -y @modelcontextprotocol/inspector@latest
```

Here you can see it in action :

<img src="../assets/examples/mcp-remote-oauth.gif" alt="mcp-server-remote-oauth" width="800" />

-----


### ➡️ MCP Client Examples (stdio)
- [quick-start-client-stdio.rs](quick-start-client-stdio.rs)
- [simple-mcp-client-stdio.rs](simple-mcp-client-stdio.rs)
- [simple-mcp-client-stdio-core.rs](simple-mcp-client-stdio-core.rs)

These examples demonstrate an MCP client using the **stdio** transport, highlighting basic MCP client operations such as retrieving the MCP server's capabilities and making a tool call.

These examples launch the [@modelcontextprotocol/server-everything](https://www.npmjs.com/package/@modelcontextprotocol/server-everything) server, an MCP Server designed for experimenting with various capabilities of the MCP.

It prints the server name and version, outlines the server's capabilities, and provides a list of available tools, prompts, templates, resources, and more offered by the server. Additionally, it will execute a "tool call" , calling the `add` tool from the `server-everything` package to sum two numbers and output the result.

> Note that @modelcontextprotocol/server-everything is an npm package, so you must have Node.js and npm installed on your system, as this example attempts to start it.

**Start the server:**
_For instance, start the `simple-mcp-client-stdio`_
```sh
cargo run --example simple-mcp-client-stdio
```



Here you can observe a sample output of the project. however, your results may vary slightly depending on the version of the MCP Server in use when you run it.

<img src="../assets/examples/mcp-client-output.jpg" width="640"/>

-----


### ➡️ MCP Client Examples (Streamable HTTP)

- [simple-mcp-client-streamable-http.rs](simple-mcp-client-streamable-http.rs)
- [simple-mcp-client-streamable-http-core.rs](simple-mcp-client-streamable-http-core.rs)

These examples demonstrate an MCP client using the *Streamable HTTP* transport, highlighting basic MCP client operations such as retrieving the MCP server's capabilities and making a tool call.

These examples connect to a running instance of the [@modelcontextprotocol/server-everything](https://www.npmjs.com/package/@modelcontextprotocol/server-everything) server, which has already been started with the `streamableHttp` argument.

It displays the server name and version, outlines the server's capabilities, and provides a list of available tools, prompts, templates, resources, and more offered by the server. Additionally, it will execute a tool call by utilizing the add tool from the server-everything package to sum two numbers and output the result.


-----

### ➡️ MCP Client Examples (SSE)

- [simple-mcp-client-sse.rs](simple-mcp-client-sse.rs)
- [simple-mcp-client-sse-core.rs](simple-mcp-client-sse-core.rs)

These examples demonstrate an MCP client using the *SSE* transport, highlighting basic MCP client operations such as retrieving the MCP server's capabilities and making a tool call.

These examples connect to a running instance of the [@modelcontextprotocol/server-everything](https://www.npmjs.com/package/@modelcontextprotocol/server-everything) server, which has been started with the `sse` argument.

It displays the server name and version, outlines the server's capabilities, and provides a list of available tools, prompts, templates, resources, and more offered by the server. Additionally, it will execute a tool call by utilizing the add tool from the server-everything package to sum two numbers and output the result.

1- First, start `@modelcontextprotocol/server-everything` with `sse` argument:
```bash
npx @modelcontextprotocol/server-everything sse
```
2- start the example client, for instance start the `simple-mcp-client-sse`:
```bash
cargo run --example simple-mcp-client-sse
```

---

### ➡️ MCP Client - Oauth Example

- [mcp-client-with-oauth.rs](mcp-client-with-oauth.rs)

A minimal MCP client example demonstrating **OAuth 2.0 client credentials flow** using the `McpAuthClient` from [rust-mcp-sdk](https://github.com/rust-mcp-stack/rust-mcp-sdk).

It features:
- Automatic OAuth metadata discovery from the server's well-known endpoint
- Dynamic Client Registration (DCR) — registers the client if no pre-registered credentials are provided
- Token exchange via `client_credentials` grant
- Automatic token refresh before expiry
- Transport integration — injects `Authorization: Bearer <token>` into request headers

**Start the client:**

```bash
cargo run --example mcp-client-with-oauth
```

> 💡 Requires an MCP server with OAuth enabled running at `http://127.0.0.1:3001/mcp`. The server must support the `client_credentials` grant type.

To use pre-registered credentials instead of DCR, pass them in the builder:

```rust
McpAuthConfig::builder()
    .server_url(MCP_SERVER_URL)
    .client_id("my-client-id")
    .client_secret("my-client-secret")
    .build()?;
```

To use a custom token store backend (e.g., SQLite, Redis), pass an `Arc<dyn TokenStore>`:

```rust
McpAuthConfig::builder()
    .server_url(MCP_SERVER_URL)
    .token_store(Arc::new(MyCustomStore::new()))
    .build()?;
```

---

## Actix-web Examples

Examples for the `rust-mcp-actix` crate (Actix-web HTTP backend) live in a separate location:

```
crates/rust-mcp-actix/examples/
```

- [`hello-world-server.rs`](../../../crates/rust-mcp-actix/examples/hello-world-server.rs) — Minimal Actix MCP server (Streamable HTTP + SSE)
- [`byo-server.rs`](../../../crates/rust-mcp-actix/examples/byo-server.rs) — Mount MCP on an existing Actix-web app using `mcp_scope()`

To run them:
```bash
cargo run -p rust-mcp-actix --example hello-world-server
cargo run -p rust-mcp-actix --example byo-server
```

Similarly, Axum BYO-server examples live in:
```
crates/rust-mcp-axum/examples/
```
- [`hello-world-server.rs`](../../../crates/rust-mcp-axum/examples/hello-world-server.rs) — Minimal Axum MCP server
- [`byo-server.rs`](../../../crates/rust-mcp-axum/examples/byo-server.rs) — Mount MCP on an existing Axum router using `mcp_routes()`

```bash
cargo run -p rust-mcp-axum --example hello-world-server
cargo run -p rust-mcp-axum --example byo-server
```