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

Several services and /mcp

One server can run several services. This page explains how they are mounted, how the combined /mcp endpoint offers all of their tools in one connector, and how each path stays its own OAuth resource.

One server, several services

Register each service with the Server builder:

use mcp_server_core::app::{Server, SignIn};
use mcp_server_core::service::{Service, ServiceEnv};
use std::sync::Arc;
fn tasks(_: &mut ServiceEnv) -> Option<Arc<dyn Service>> { None }
fn calendar(_: &mut ServiceEnv) -> Option<Arc<dyn Service>> { None }

#[tokio::main]
async fn main() -> std::process::ExitCode {
    Server::new("mcp-planner", env!("CARGO_PKG_VERSION"))
        .env_prefix("PLANNER")
        .service("tasks", tasks)
        .service("calendar", calendar)
        .sign_in(SignIn::OwnerPassword)
        .main()
        .await
}

With PUBLIC_URL=https://mcp.example.com, the server answers on:

PathServes
/tasksThe tasks service: its tools, prompts and, if its router serves them, resources
/calendarThe calendar service
/mcpEvery enabled service’s tools and prompts, each name prefixed with its service

PLANNER_SERVICES=tasks runs only some of the registered services; an unselected service is not mounted, is not on /mcp and reads none of its configuration. Services are mounted, and listed on /mcp, in registration order, or in the order PLANNER_SERVICES names them when it is set. See the configuration reference for <PREFIX>_SERVICES.

The combined endpoint

/mcp is one MCP server built from every enabled service’s handler. A client connected to it sees every service at once, with one sign-in.

Tool names

Each tool is offered as <service>_<tool>: the tasks service’s add_task is tasks_add_task on /mcp, and calendar’s list_events is calendar_list_events. A tool’s description, input schema and annotations are unchanged.

A call is routed by its prefix. Service names never contain _, so the first _ ends the prefix; the call reaches that service’s handler under the tool’s own name, add_task. Tool names themselves may contain _. A name with no enabled service as its prefix is answered with a JSON-RPC invalid_params error, tool not found.

What initialize returns

FieldValue on /mcp
serverInfoThe server’s name and version from Server::new, and its icons from Server::icon
capabilitiesTools always; prompts when any enabled service declares them; never resources
instructionsA short guide to the prefixes, then each service’s own instructions under its name

The instructions start with a fixed paragraph naming the prefixes, and add each service’s instructions, trimmed, after a line with its name. Services without instructions, or with blank ones, are left out:

#![allow(unused)]
fn main() {
use mcp_server_core::combined::{Combined, DynHandler};
use mcp_server_core::rmcp::ServerHandler;
use mcp_server_core::rmcp::model::{Implementation, ServerCapabilities, ServerConfig};

#[derive(Clone)]
struct Tools(&'static str);

impl ServerHandler for Tools {
    fn get_info(&self) -> ServerConfig {
        ServerConfig::new(ServerCapabilities::builder().enable_tools().build())
            .with_instructions(self.0)
    }
}

let combined = Combined::new(
    Implementation::new("mcp-planner", "1.0.0"),
    vec![
        ("tasks", DynHandler::new(Tools("Keeps a task list. Dates are YYYY-MM-DD.\n"))),
        ("calendar", DynHandler::new(Tools("Times are in UTC."))),
    ],
);
assert_eq!(
    combined.get_info().instructions.unwrap(),
    "This server combines several services. Each tool and prompt name starts with its \
     service: tasks_, calendar_. The notes below, tool descriptions and error messages \
     name tools without that prefix.\n\
     \n\
     tasks:\n\
     Keeps a task list. Dates are YYYY-MM-DD.\n\
     \n\
     calendar:\n\
     Times are in UTC."
);
}

Write your service’s instructions and tool descriptions for its own path, naming tools without a prefix; the first paragraph tells the model how to read them on /mcp.

Prompts and resources

Prompts are offered as <service>_<prompt>, and tool names in a prompt’s text are prefixed for you. Prompts has the details.

Resources are served on each service’s own path only. /mcp forwards tools and prompts, nothing else.

Read-only services and the audit log

Each service keeps its own read-only rule on /mcp. With PLANNER_READ_ONLY=calendar:

  • /mcp lists every tasks_ tool, but only the calendar_ tools marked read_only_hint = true;
  • calling a hidden calendar_ write tool returns the tool error read_only: the calendar service is read-only on this server;
  • tasks_ write tools work as on /tasks.

Every write tool call on /mcp is audited as on the service’s own path, with endpoint set to /mcp, service to the service and tool to its own name without the prefix, such as add_task. See Read-only mode and the audit log.

Who is calling

A call forwarded from /mcp keeps its request context, so a tool reads the Caller and the person’s Credential from the request extensions exactly as on its own path.

Turning /mcp off

/mcp is served whenever at least one service is enabled, even a single one. Set <PREFIX>_COMBINED=false (PLANNER_COMBINED=false here) to turn it off; it accepts true, false, 1, 0, yes, no, on and off in any case, and anything else stops startup with PLANNER_COMBINED must be true or false, got "<value>". Then /mcp and its metadata document answer 404, and mcp is no longer listed in the authorization server’s scopes_supported.

Keep it on when people want one connector for everything. Turn it off when every client should be given one service at a time: a token for /tasks never works on /calendar, while a token for /mcp reaches every service.

Service names

Because the name is the path, the OAuth resource and the prefix on /mcp, a service name must be lowercase ASCII letters, digits and -, never mcp, and unique. _ is excluded so a prefixed name can always be split, and mcp is the combined endpoint itself. Server::service panics on a name that breaks these rules; see Names for the messages.

Each path is its own OAuth resource

Every path, /mcp included, is a separate OAuth 2.1 protected resource:

For /tasksFor /mcp
Resourcehttps://mcp.example.com/taskshttps://mcp.example.com/mcp
Metadata document/.well-known/oauth-protected-resource/tasks/.well-known/oauth-protected-resource/mcp
scopes_supported in it["tasks"]["mcp"]
Sign-in page says“the tasks service on this server”“every service on this server, through /mcp”
  • A request without a token gets 401 with a WWW-Authenticate header naming that path’s metadata document, so a client signs in for the path it was given.
  • An access token is bound to the resource it was issued for (RFC 8707). A token for /mcp is refused on /tasks and the other way round, with 401 and error="invalid_token". A refresh keeps the resource; asking for another one fails with invalid_target.
  • One sign-in page, and one password or credential, covers every path.
  • A client that sends no resource parameter when it signs in gets the only service when there is exactly one; /mcp is never chosen for it. With several services such a request fails with invalid_target: resource is required: name the URL of the service, or of /mcp for every service.
  • The static token (MCP_AUTH_TOKEN) and a person’s credential sent directly as the bearer token are not bound to a path: they work on every path.
  • MCP sessions belong to the path that opened them, and each path keeps its own session table and caps; see Limits and abuse protection.

Resource indicators and audiences and Choosing the resource explain the tokens in full, and Which URL to use which URL to give each client.

Next: Prompts.