Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Examples

The repository has two complete servers in examples/. This page says what each one shows, how to run it, and what to try against it.

ExampleSign-inShows
notesThe owner’s passwordA read tool and a write tool, tool arguments, tool errors, read-only mode, the static token and the audit log
api_keysEach person’s own API keyA CredentialVerifier, a tool that reads the caller’s key, keys sent directly as bearer tokens, sessions bound to a key

With the commands below, both listen on 0.0.0.0:8443 and serve plain HTTP for localhost, so nothing needs a certificate. Run them from a clone of the repository:

git clone https://github.com/Trozz/mcp-server-core-rs
cd mcp-server-core-rs

notes: a server for its owner

examples/notes.rs keeps short notes for one person. It is the quick start server with more in it:

  • The service notes, at /notes, with environment prefix NOTES.
  • list_notes, marked read_only_hint = true, and add_note, marked read_only_hint = false, which takes a text argument through Parameters<AddNote>.
  • add_note returns the tool error invalid_argument: text is empty for blank text, so the audit log records the kind invalid_argument.
  • The notes live in an Arc<Mutex<Vec<String>>> held by the service and cloned into each session’s handler, so every session sees the same notes. They are lost when the server stops.
  • tool_names lists both tools for the startup log, and the handler sets the instructions Keeps short notes.

Run it:

PUBLIC_URL=http://localhost:8443 INSECURE_HTTP=true \
OAUTH_SIGNING_KEY=$(openssl rand -hex 32) OAUTH_ADMIN_PASSWORD='a long password' \
LOG_FORMAT=pretty cargo run --example notes

Then add http://localhost:8443/notes to an MCP client, or open the MCP Inspector with npx @modelcontextprotocol/inspector and connect to that URL over Streamable HTTP. The client registers itself and opens the sign-in page in your browser; enter a long password. Ask it to add a note and list them.

Things to try with notes

Every tool on one path. Connect to http://localhost:8443/mcp instead. The tools are notes_add_note and notes_list_notes, and the instructions start with the paragraph about prefixes described in Several services and /mcp.

Read-only mode. Restart with NOTES_READ_ONLY=notes. tools/list now offers only list_notes (notes_list_notes on /mcp), and calling add_note anyway returns the tool error:

read_only: the notes service is read-only on this server

The static token and curl. Restart with a static token and an audit log:

export MCP_AUTH_TOKEN=$(openssl rand -hex 32)
PUBLIC_URL=http://localhost:8443 INSECURE_HTTP=true \
OAUTH_SIGNING_KEY=$(openssl rand -hex 32) OAUTH_ADMIN_PASSWORD='a long password' \
AUDIT_LOG_PATH=./audit.jsonl LOG_FORMAT=pretty cargo run --example notes

In another terminal with the same MCP_AUTH_TOKEN, open a session and call the tools. Each request after initialize names the session in Mcp-Session-Id:

URL=http://localhost:8443/notes
H=(-H "Authorization: Bearer $MCP_AUTH_TOKEN" -H 'Content-Type: application/json'
   -H 'Accept: application/json, text/event-stream')
SESSION=$(curl -s -D - -o /dev/null "${H[@]}" $URL \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}' \
  | awk 'tolower($1) == "mcp-session-id:" {print $2}' | tr -d '\r')
H+=(-H "Mcp-Session-Id: $SESSION" -H 'MCP-Protocol-Version: 2025-06-18')
curl -s "${H[@]}" $URL -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'
curl -s "${H[@]}" $URL \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"add_note","arguments":{"text":"Buy milk"}}}'
curl -s "${H[@]}" $URL \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"add_note","arguments":{"text":" "}}}'
curl -s "${H[@]}" $URL \
  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"list_notes","arguments":{}}}'

Each answer is a short server-sent event stream whose last data: line holds the JSON-RPC response, such as {"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"added"}],"isError":false}}. audit.jsonl now has one line for each add_note call, and none for list_notes, which only reads:

{"ts":"2026-10-18T13:49:04.714Z","service":"notes","endpoint":"/notes","tool":"add_note","outcome":"ok","error_kind":null,"caller":"static","subject":"static","elapsed_ms":0}
{"ts":"2026-10-18T13:49:04.724Z","service":"notes","endpoint":"/notes","tool":"add_note","outcome":"error","error_kind":"invalid_argument","caller":"static","subject":"static","elapsed_ms":0}

A call signed in through OAuth records caller as oauth:<client_id> and subject as owner. Read-only mode and the audit log explains every field.

The binary’s flags and configuration errors. cargo run --example notes -- --version prints the name and version, such as mcp-notes 0.4.0. Run it without any environment and it lists every missing variable, then exits with status 1:

configuration error: PUBLIC_URL is required
configuration error: OAUTH_SIGNING_KEY is required
configuration error: OAUTH_ADMIN_PASSWORD is required

api_keys: a server shared by many people

examples/api_keys.rs is a server where each person signs in with their own key for an upstream API, so one deployment serves many people without holding anyone’s key. The “upstream API” is imaginary: it accepts any key that starts with demo- and has something after it.

  • SignIn::ServiceCredential, with environment prefix DEMO. There is no owner’s password, so OAUTH_ADMIN_PASSWORD is not needed.

  • The service account, at /account, returns a CredentialVerifier from credential_verifier:

    MethodIn the example
    labelDemo API key, shown on the sign-in page
    helpAny key starting demo- works, such as demo-1234., shown under the field
    plausibleStarts with demo- and is at most 64 bytes. Anything else is refused locally, without asking upstream and without counting as a failed attempt
    checkValid when something follows demo-, otherwise Invalid with the reason That key is empty after demo-. A real verifier makes one cheap authenticated request upstream here, and answers Unavailable when the upstream cannot be reached
  • The tool whoami takes Extension<Parts> and reads the caller’s key as a Credential, answering with its last four characters.

Run it:

PUBLIC_URL=http://localhost:8443 INSECURE_HTTP=true \
OAUTH_SIGNING_KEY=$(openssl rand -hex 32) LOG_FORMAT=pretty \
cargo run --example api_keys

Then add http://localhost:8443/account to an MCP client and sign in with demo-1234. Calling whoami answers You are using the key ending 1234.

Things to try with api_keys

The sign-in page. It asks for a “Demo API key” and says the key is checked once and then kept only in encrypted form inside the connection’s tokens. Enter abc and it answers That is not a Demo API key., without counting the attempt. Enter demo- and it shows the verifier’s reason, That key is empty after demo-.; that one counts. After five rejected attempts from your address within a minute, the next is refused with 429: Too many attempts from this address: credentials were rejected, or several are being checked at once. Wait a little and try again. See Limits and abuse protection.

The key as the bearer token. A client that can send a header may skip OAuth and send the key itself:

claude mcp add --transport http account http://localhost:8443/account \
  --header "Authorization: Bearer demo-1234"

The server checks the key with the verifier and remembers the verdict for a while under the key’s SHA-256 (ten minutes for a valid key, one minute for a rejected one), so it does not ask upstream on every request (see Credentials sent as bearer tokens). A rejected or implausible key gets 401 with a WWW-Authenticate header naming the service’s metadata and error="invalid_token".

Sessions belong to a key. Open a session with demo-1234, then send a request in that session (the same Mcp-Session-Id) with demo-9999: it gets 404, as if the session did not exist, so one person can never use another’s session.

No static token. Start it with MCP_AUTH_TOKEN set and it refuses:

configuration error: MCP_AUTH_TOKEN cannot be used when people sign in with their own Demo API key

Requests made with a fixed token would carry no key for the tools to call upstream with. The static token explains the rules.

From an example to your own server

Copy the example closest to what you need, rename the service and the prefix, and replace the tools. Each example starts with use mcp_server_core::rmcp; so rmcp’s macros find the crate in your own project too (see Writing tools with rmcp); for notes, also cargo add serde --features derive. Writing a service covers reading your service’s configuration, and The CredentialVerifier trait writing a verifier for a real upstream API. The two servers built on this crate are larger examples of the same shapes: mcp-icloud signs its owner in with a password, and mcp-companies-house signs each person in with their own Companies House API key.

Next: Sign-in modes.