RMCP

https://docs.rs/rmcp/latest/rmcp/
Admin
RMCP is the official Rust SDK for the Model Context Protocol, enabling AI assistants to communicate...
Tokens:1,415,468
Snippets:16,260
Trust Score:9.7
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Create ServerConfig with tools and instructions

Source: https://docs.rs/rmcp/latest/rmcp/model/type.ServerConfig.html

Creates a ServerConfig with tool capabilities and instructions, then asserts the tools capability is present.

```rust
use rmcp::model::{ServerCapabilities, ServerConfig};

let config = ServerConfig::new(ServerCapabilities::builder().enable_tools().build())
    .with_instructions("Call `add` to sum two numbers.");
assert!(config.capabilities.tools.is_some());
```

--------------------------------

### Get a reference from Extensions

Source: https://docs.rs/rmcp/latest/rmcp/model/struct.Extensions.html?search=std%3A%3Avec

Example for `get` method: retrieves a reference to a previously inserted type.

```rust
let mut ext = Extensions::new();
assert!(ext.get::<i32>().is_none());
ext.insert(5i32);

assert_eq!(ext.get::<i32>(), Some(&5i32));
```

--------------------------------

### initialize

Source: https://docs.rs/rmcp/latest/rmcp/handler/server/trait.ServerHandler.html?search=

Initializes the server with the given request parameters.

```APIDOC
## initialize

### Description
Initializes the server with the given request parameters.

### Method
Trait method

### Signature
`fn initialize(&self, request: InitializeRequestParams, context: RequestContext<RoleServer>) -> impl Future<Output = Result<InitializeResult, McpError>> + MaybeSendFuture + '_`

### Parameters
- **request** (InitializeRequestParams) - Required - The initialization request parameters.
- **context** (RequestContext<RoleServer>) - Required - The request context.

### Returns
- **Result<InitializeResult, McpError>** - The initialization result or an error.
```

--------------------------------

### Arc::weak_count example

Source: https://docs.rs/rmcp/latest/rmcp/transport/common/server_side_http/type.SessionId.html

Gets the number of `Weak` pointers to the allocation. The example creates an `Arc`, downgrades it, and asserts the weak count is 1.

```rust
use std::sync::Arc;

let five = Arc::new(5);
let _weak_five = Arc::downgrade(&five);

// This assertion is deterministic because we haven't shared
// the `Arc` or `Weak` between threads.
assert_eq!(1, Arc::weak_count(&five));
```

--------------------------------

### Create ClientConfig with capabilities

Source: https://docs.rs/rmcp/latest/rmcp/model/type.ClientConfig.html

Shows how to create a ClientConfig with capabilities and implementation info, then asserts the elicitation capability is set.

```rust
use rmcp::model::{ClientCapabilities, ClientConfig, Implementation};

let config = ClientConfig::new(
    ClientCapabilities::builder().enable_elicitation().build(),
    Implementation::new("my-client", "1.0.0"),
);
assert!(config.capabilities.elicitation.is_some());
```

--------------------------------

### Arc::strong_count example

Source: https://docs.rs/rmcp/latest/rmcp/transport/common/server_side_http/type.SessionId.html

Gets the number of strong (`Arc`) pointers to the allocation. The example creates an `Arc`, clones it, and asserts the strong count is 2.

```rust
use std::sync::Arc;

let five = Arc::new(5);
let _also_five = Arc::clone(&five);

// This assertion is deterministic because we haven't shared
// the `Arc` between threads.
assert_eq!(2, Arc::strong_count(&five));
```

--------------------------------

### Pin::into_inner example

Source: https://docs.rs/rmcp/latest/rmcp/task_manager/type.TaskFuture.html?search=

Example for `Pin::into_inner` showing safe unwrapping of a `Pin` to get the underlying pointer. Available with crate features `client` or `server`.

```rust
use std::pin::Pin;

let mut val: u8 = 5;
let pinned: Pin<&mut u8> = Pin::new(&mut val);

// Unwrap the pin to get the underlying mutable reference to the value. We can do
// this because `val` doesn't care about being moved, so the `Pin` was just
// a "facade" anyway.
let r = Pin::into_inner(pinned);
assert_eq!(*r, 5);
```

--------------------------------

### ServerConfig::with_instructions

Source: https://docs.rs/rmcp/latest/rmcp/model/type.ServerConfig.html

Sets the instructions on this ServerConfig and returns the modified instance.

```APIDOC
## ServerConfig::with_instructions

### Description
Sets the instructions on this `ServerConfig` and returns the modified instance.

### Method
`pub fn with_instructions(self, instructions: impl Into<String>) -> Self`

### Parameters
- **instructions** (impl Into<String>) - Required - The instructions to set.

### Returns
- **Self** - The modified `ServerConfig`.

### Example
```rust
use rmcp::model::{ServerCapabilities, ServerConfig};
let config = ServerConfig::new(ServerCapabilities::builder().build())
    .with_instructions("Call `add` to sum two numbers.");
```
```

--------------------------------

### ServerPeerInfo::with_instructions

Source: https://docs.rs/rmcp/latest/rmcp/model/struct.ServerPeerInfo.html

Sets instructions supplied by the server on the peer info and returns the modified instance.

```APIDOC
## ServerPeerInfo::with_instructions

### Description
Set instructions supplied by the server.

### Method
with_instructions

### Signature
pub fn with_instructions(self, instructions: impl Into<String>) -> Self

### Parameters
- **instructions** (impl Into<String>) - Required - The instructions to set.

### Returns
- **Self** - The modified ServerPeerInfo instance.
```

--------------------------------

### BTreeMap::range example

Source: https://docs.rs/rmcp/latest/rmcp/model/type.ExperimentalCapabilities.html

Iterates over a sub-range of elements using range syntax or Bound tuples. Panics if start > end or if start == end and both bounds are Excluded.

```rust
use std::collections::BTreeMap;
use std::ops::Bound::Included;

let mut map = BTreeMap::new();
map.insert(3, "a");
map.insert(5, "b");
map.insert(8, "c");
for (&key, &value) in map.range((Included(&4), Included(&8))) {
    println!("{key}: {value}");
}
assert_eq!(Some((&5, &"b")), map.range(4..).next());
```

--------------------------------

### InitializeResult::with_instructions

Source: https://docs.rs/rmcp/latest/rmcp/model/struct.InitializeResult.html?search=std%3A%3Avec

Sets the instructions on this result and returns the modified result.

```APIDOC
## InitializeResult::with_instructions

### Description
Sets the instructions on this result and returns the modified result.

### Method
`pub fn with_instructions(self, instructions: impl Into<String>) -> Self`

### Parameters
- **instructions** (`impl Into<String>`) - Required - Optional human-readable instructions about using this server.

### Returns
- `Self` - The modified `InitializeResult`.

### Example
```rust
let result = result.with_instructions("Use with caution");
```
```

--------------------------------

### Get the number of extensions

Source: https://docs.rs/rmcp/latest/rmcp/model/struct.Extensions.html?search=std%3A%3Avec

Example for `len` method: returns the number of extensions available.

```rust
let mut ext = Extensions::new();
assert_eq!(ext.len(), 0);
ext.insert(5i32);
assert_eq!(ext.len(), 1);
```

--------------------------------

### Example: building an elicitation schema

Source: https://docs.rs/rmcp/latest/rmcp/model/struct.ElicitationSchemaBuilder.html

Shows how to use the builder to create a schema with required email, required integer, optional boolean, and a description.

```rust
use rmcp::model::*;

let schema = ElicitationSchema::builder()
    .required_email("email")
    .required_integer("age", 0, 150)
    .optional_bool("newsletter", false)
    .description("User registration")
    .build();
```

--------------------------------

### as_bytes example

Source: https://docs.rs/rmcp/latest/rmcp/model/type.Cursor.html

Shows how to get a byte slice of a `String` using `as_bytes`. The inverse method is `from_utf8`.

```rust
let s = String::from("hello");

assert_eq!(&[104, 101, 108, 108, 111], s.as_bytes());

```

--------------------------------

### negotiate_initialize

Source: https://docs.rs/rmcp/latest/rmcp/handler/server/trait.ServerHandler.html?search=

Builds the `initialize` response for `request`, negotiating the protocol version against `Self::supported_protocol_versions`.

```APIDOC
## negotiate_initialize

### Description
Builds the `initialize` response for `request`, negotiating the protocol version against `Self::supported_protocol_versions`.

### Method
Trait method

### Signature
`fn negotiate_initialize(&self, request: &InitializeRequestParams) -> Result<InitializeResult, McpError>`

### Parameters
- **request** (&InitializeRequestParams) - Required - The initialization request parameters.

### Returns
- **Result<InitializeResult, McpError>** - The negotiated initialization result or an error.

### Errors
Returns `ErrorCode::UNSUPPORTED_PROTOCOL_VERSION` when this server supports no version that still has an `initialize` handshake.
```

--------------------------------

### Get or insert with a closure into Extensions

Source: https://docs.rs/rmcp/latest/rmcp/model/struct.Extensions.html?search=std%3A%3Avec

Example for `get_or_insert_with` method: inserts a value created by a closure if not present.

```rust
let mut ext = Extensions::new();
*ext.get_or_insert_with(|| 1i32) += 2;

assert_eq!(*ext.get::<i32>().unwrap(), 3);
```

--------------------------------

### BTreeMap::new Example

Source: https://docs.rs/rmcp/latest/rmcp/model/type.ExperimentalCapabilities.html

Creates an empty BTreeMap and inserts an entry.

```rust
use std::collections::BTreeMap;

let mut map = BTreeMap::new();

// entries can now be inserted into the empty map
map.insert(1, "a");
```

--------------------------------

### Get or insert a value into Extensions

Source: https://docs.rs/rmcp/latest/rmcp/model/struct.Extensions.html?search=std%3A%3Avec

Example for `get_or_insert` method: inserts a value if not present, then returns a mutable reference.

```rust
let mut ext = Extensions::new();
*ext.get_or_insert(1i32) += 2;

assert_eq!(*ext.get::<i32>().unwrap(), 3);
```

--------------------------------

### ServerHandler::initialize

Source: https://docs.rs/rmcp/latest/rmcp/handler/server/trait.ServerHandler.html?search=u32+-%3E+bool

Initializes the MCP session.

```APIDOC
## ServerHandler::initialize

### Description
Initializes the MCP session.

### Method
Trait method

### Signature
```rust
fn initialize(&self, request: InitializeRequestParams, context: RequestContext<RoleServer>) -> impl Future<Output = Result<InitializeResult, McpError>> + MaybeSendFuture + '_;
```

### Parameters
- **request** (InitializeRequestParams) - Required - The initialization request parameters.
- **context** (RequestContext<RoleServer>) - Required - The request context.

### Returns
- A future that resolves to `Result<InitializeResult, McpError>`.

### Availability
- **non-crate feature `local`** only.
```

--------------------------------

### Get a mutable reference from Extensions

Source: https://docs.rs/rmcp/latest/rmcp/model/struct.Extensions.html?search=std%3A%3Avec

Example for `get_mut` method: retrieves a mutable reference to a previously inserted type.

```rust
let mut ext = Extensions::new();
ext.insert(String::from("Hello"));
ext.get_mut::<String>().unwrap().push_str(" World");

assert_eq!(ext.get::<String>().unwrap(), "Hello World");
```

--------------------------------

### Create and insert extension capabilities

Source: https://docs.rs/rmcp/latest/rmcp/model/type.ExtensionCapabilities.html

Shows how to create an ExtensionCapabilities map and insert an extension entry with settings. The example uses the extension identifier io.modelcontextprotocol/ui and a JSON object with a mimeTypes array.

```rust
use rmcp::model::ExtensionCapabilities;
use serde_json::json;

let mut extensions = ExtensionCapabilities::new();
extensions.insert(
    "io.modelcontextprotocol/ui".to_string(),
    serde_json::from_value(json!({
        "mimeTypes": ["text/html;profile=mcp-app"]
    })).unwrap()
);
```

--------------------------------

### Get or insert default value into Extensions

Source: https://docs.rs/rmcp/latest/rmcp/model/struct.Extensions.html?search=std%3A%3Avec

Example for `get_or_insert_default` method: inserts the type's default value if not present.

```rust
let mut ext = Extensions::new();
*ext.get_or_insert_default::<i32>() += 2;

assert_eq!(*ext.get::<i32>().unwrap(), 2);
```

--------------------------------

### capacity: Get String capacity in bytes

Source: https://docs.rs/rmcp/latest/rmcp/model/type.Cursor.html

Returns the current capacity in bytes. The example shows that capacity is at least the requested amount.

```rust
let s = String::with_capacity(10);

assert!(s.capacity() >= 10);
```

--------------------------------

### Constructing uninitialized box with Box::new_uninit_in

Source: https://docs.rs/rmcp/latest/rmcp/transport/auth/type.OAuthHttpClientError.html?search=

This example shows how to create a Box with uninitialized contents using a provided allocator. It requires the nightly feature allocator_ext and the non-no_global_oom_handling feature.

```rust
#![feature(allocator_ext)]

use std::alloc::System;
```

--------------------------------

### ServerHandler::negotiate_initialize

Source: https://docs.rs/rmcp/latest/rmcp/handler/server/trait.ServerHandler.html?search=u32+-%3E+bool

Negotiates the initialization parameters.

```APIDOC
## ServerHandler::negotiate_initialize

### Description
Negotiates the initialization parameters.

### Method
Trait method

### Signature
```rust
fn negotiate_initialize(&self, request: &InitializeRequestParams) -> Result<InitializeResult, McpError>;
```

### Parameters
- **request** (&InitializeRequestParams) - Required - The initialization request parameters.

### Returns
- **Result<InitializeResult, McpError>** - The initialization result or an error.

### Availability
- **non-crate feature `local`** only.
```

--------------------------------

### strong_count_from_raw example

Source: https://docs.rs/rmcp/latest/rmcp/transport/common/server_side_http/type.SessionId.html

Demonstrates using the nightly-only experimental API arc_raw_get_strong to get the strong count from a raw pointer. Requires the 'client' feature and the arc_raw_get_strong feature gate. The example shows cloning an Arc and converting back to avoid memory leak.

```rust
#![feature(arc_raw_get_strong)]
use std::sync::Arc;

let five = Arc::new(5);
let _also_five = Arc::clone(&five);
let ptr = Arc::into_raw(five);

unsafe {
    // This assertion is deterministic because we haven't shared
    // the `Arc` between threads.
    assert_eq!(2, Arc::strong_count_from_raw(ptr));

    // Convert back to an `Arc` to avoid leaking memory.
    let five = Arc::from_raw(ptr);
    assert_eq!(2, Arc::strong_count(&five));
}
```

--------------------------------

### BTreeMap::last_key_value example

Source: https://docs.rs/rmcp/latest/rmcp/model/type.ExperimentalCapabilities.html

Shows how to get the last (maximum) key-value pair in a BTreeMap using last_key_value. Returns None when the map is empty.

```rust
use std::collections::BTreeMap;

let mut map = BTreeMap::new();
map.insert(1, "b");
map.insert(2, "a");
assert_eq!(map.last_key_value(), Some((&2, &"a")));
```

--------------------------------

### Box::new_uninit_in deferred initialization

Source: https://docs.rs/rmcp/latest/rmcp/transport/auth/type.OAuthHttpClientError.html?search=

Example for `Box::new_uninit_in` showing deferred initialization with `write` and `assume_init`. Requires the nightly `allocator_ext` feature and `use std::alloc::System;`.

```rust
let mut five = Box::<u32, _>::new_uninit_in(System);
// Deferred initialization:
five.write(5);
let five = unsafe { five.assume_init() };

assert_eq!(*five, 5)
```

--------------------------------

### serve

Source: https://docs.rs/rmcp/latest/rmcp/service/trait.ServiceExt.html?search=u32+-%3E+bool

The `serve` method starts a service on the given transport using a default cancellation token. It encapsulates the transport construction and initialization.

```APIDOC
## serve

### Description
Starts serving the service on the given transport and returns a future that resolves to a RunningService. This is a convenience wrapper around `serve_with_ct` that creates a new cancellation token.

### Method
serve

### Signature
```rust
fn serve<T, E, A>(
    self,
    transport: T,
) -> impl Future<Output = Result<RunningService<R, Self>, R::InitializeError>> + MaybeSendFuture
where
    T: IntoTransport<R, E, A>,
    E: Error + Send + Sync + 'static,
    Self: Sized;
```

### Parameters
- **transport** (T) - Required - The transport used to serve the service.

### Returns
A future that resolves to `Result<RunningService<R, Self>, R::InitializeError>`, where `R` is the service role.
```

--------------------------------

### BTreeMap::first_key_value example

Source: https://docs.rs/rmcp/latest/rmcp/model/type.ExperimentalCapabilities.html

Shows how to get the first (minimum) key-value pair in a BTreeMap using first_key_value. Returns None when the map is empty.

```rust
use std::collections::BTreeMap;

let mut map = BTreeMap::new();
assert_eq!(map.first_key_value(), None);
map.insert(1, "b");
map.insert(2, "a");
assert_eq!(map.first_key_value(), Some((&1, &"b")));
```

--------------------------------

### Get string slice with String::as_str

Source: https://docs.rs/rmcp/latest/rmcp/model/type.Cursor.html

Extracts a string slice containing the entire String. The example asserts equality with a string literal.

```rust
let s = String::from("foo");

assert_eq!("foo", s.as_str());
```

--------------------------------

### Manually create Box from scratch using global allocator

Source: https://docs.rs/rmcp/latest/rmcp/transport/auth/type.OAuthHttpClientError.html?search=

Example for Box::from_raw: manually creates a Box from scratch using the global allocator. Uses ptr.write to avoid destructing uninitialized memory.

```rust
use std::alloc::{alloc, Layout};

unsafe {
    let ptr = alloc(Layout::new::<i32>()) as *mut i32;
    // In general .write is required to avoid attempting to destruct
    // the (uninitialized) previous contents of `ptr`, though for this
    // simple example `*ptr = 5` would have worked as well.
    ptr.write(5);
    let x = Box::from_raw(ptr);
}
```

--------------------------------

### PromptContext::new

Source: https://docs.rs/rmcp/latest/rmcp/handler/server/prompt/struct.PromptContext.html

Creates a new PromptContext instance with the given server reference, prompt name, arguments, and request context.

```APIDOC
## PromptContext::new

### Description
Creates a new `PromptContext` instance with the provided server reference, prompt name, arguments, and request context.

### Method
`pub fn new(server: &'a S, name: String, arguments: Option<Map<String, Value>>, context: RequestContext<RoleServer>) -> Self`

### Parameters
- **server** (`&'a S`) - Required - Reference to the server.
- **name** (`String`) - Required - The name of the prompt.
- **arguments** (`Option<Map<String, Value>>`) - Required - Optional arguments for the prompt.
- **context** (`RequestContext<RoleServer>`) - Required - The request context.

### Returns
- `Self` - A new `PromptContext` instance.

```

--------------------------------

### Arc::increment_strong_count_in example

Source: https://docs.rs/rmcp/latest/rmcp/transport/common/server_side_http/type.SessionId.html

Increments the strong reference count on the `Arc<T>` associated with the provided pointer by one. Requires the nightly-only `allocator_ext` feature. The example uses `Arc::new_in` with `System` allocator and `Arc::into_raw_with_allocator` to get the pointer, then increments the count and verifies it.

```rust
#![feature(allocator_ext)]

use std::sync::Arc;
use std::alloc::System;

let five = Arc::new_in(5, System);

unsafe {
    let (ptr, _alloc) = Arc::into_raw_with_allocator(five);
    Arc::increment_strong_count_in(ptr, System);

    // This assertion is deterministic because we haven't shared
    // the `Arc` between threads.
    let five = Arc::from_raw_in(ptr, System);
    assert_eq!(2, Arc::strong_count(&five));
}
```

--------------------------------

### serve_server_with_ct

Source: https://docs.rs/rmcp/latest/rmcp/service/fn.serve_server_with_ct.html

Starts the server service with the provided transport and cancellation token, returning a RunningService for the server role.

```APIDOC
## serve_server_with_ct

### Description
Starts the server service with the provided transport and cancellation token, returning a RunningService for the server role.

### Function Signature
```rust
pub async fn serve_server_with_ct<S, T, E, A>(
    service: S,
    transport: T,
    ct: CancellationToken,
) -> Result<RunningService<RoleServer, S>, ServerInitializeError>
where
    S: Service<RoleServer>,
    T: IntoTransport<RoleServer, E, A>,
    E: Error + Send + Sync + 'static,
```

### Parameters
- **service** (S) - Required - The server service to run.
- **transport** (T) - Required - The transport to use for communication.
- **ct** (CancellationToken) - Required - A cancellation token to control the server lifecycle.

### Return Value
- **Result<RunningService<RoleServer, S>, ServerInitializeError>** - On success, returns a running server service handle; on failure, returns a server initialization error.

### Availability
Available on **crate feature `server` and (crate features `client` or `server`)** only.
```

--------------------------------

### into_inner examples

Source: https://docs.rs/rmcp/latest/rmcp/transport/common/server_side_http/type.SessionId.html?search=u32+-%3E+bool

Two examples for Arc::into_inner. The first demonstrates the guarantee that exactly one of two threads gets the inner value. The second shows a practical use in a manual Drop implementation for a linked list to avoid stack overflow, contrasting with try_unwrap.

```rust
use std::sync::Arc;

let x = Arc::new(3);
let y = Arc::clone(&x);

// Two threads calling `Arc::into_inner` on both clones of an `Arc`:
let x_thread = std::thread::spawn(|| Arc::into_inner(x));
let y_thread = std::thread::spawn(|| Arc::into_inner(y));

let x_inner_value = x_thread.join().unwrap();
let y_inner_value = y_thread.join().unwrap();

// One of the threads is guaranteed to receive the inner value:
assert!(matches!(
    (x_inner_value, y_inner_value),
    (None, Some(3)) | (Some(3), None)
));
// The result could also be `(None, None)` if the threads called
// `Arc::try_unwrap(x).ok()` and `Arc::try_unwrap(y).ok()` instead.
```

```rust
use std::sync::Arc;

// Definition of a simple singly linked list using `Arc`:
#[derive(Clone)]
struct LinkedList<T>(Option<Arc<Node<T>>>);
struct Node<T>(T, Option<Arc<Node<T>>>);

// Dropping a long `LinkedList<T>` relying on the destructor of `Arc`
// can cause a stack overflow. To prevent this, we can provide a
// manual `Drop` implementation that does the destruction in a loop:
impl<T> Drop for LinkedList<T> {
    fn drop(&mut self) {
        let mut link = self.0.take();
        while let Some(arc_node) = link.take() {
            if let Some(Node(_value, next)) = Arc::into_inner(arc_node) {
                link = next;
            }
        }
    }
}

// Implementation of `new` and `push` omitted
impl<T> LinkedList<T> {
    /* ... */
}

// The following code could have still caused a stack overflow
// despite the manual `Drop` impl if that `Drop` impl had used
// `Arc::try_unwrap(arc).ok()` instead of `Arc::into_inner(arc)`.

// Create a long list and clone it
let mut x = LinkedList::new();
let size = 100000;
for i in 0..size {
    x.push(i); // Adds i to the front of x
}
let y = x.clone();

// Drop the clones in parallel
let x_thread = std::thread::spawn(|| drop(x));
let y_thread = std::thread::spawn(|| drop(y));
x_thread.join().unwrap();
y_thread.join().unwrap();
```

--------------------------------

### Pin::new example

Source: https://docs.rs/rmcp/latest/rmcp/task_manager/type.TaskFuture.html?search=

Example for `Pin::new` showing safe construction of a `Pin` around an `Unpin` value. Available with crate features `client` or `server`.

```rust
use std::pin::Pin;

let mut val: u8 = 5;

// Since `val` doesn't care about being moved, we can safely create a "facade" `Pin`
// which will allow `val` to participate in `Pin`-bound apis  without checking that
// pinning guarantees are actually upheld.
let mut pinned: Pin<&mut u8> = Pin::new(&mut val);
```

--------------------------------

### Get mutable string slice with String::as_mut_str

Source: https://docs.rs/rmcp/latest/rmcp/model/type.Cursor.html

Converts a String into a mutable string slice, allowing in-place modification. The example uppercases the contents and asserts the result.

```rust
let mut s = String::from("foobar");
let s_mut_str = s.as_mut_str();

s_mut_str.make_ascii_uppercase();

assert_eq!("FOOBAR", s_mut_str);
```
Tokens:
Raw