clarify that the server owns tools

simonpcouch · simonpcouch · commit fa1b1ee08c87 · 2025-10-28T13:47:00.000-05:00
Closes #71.
diff --git a/R/server.R b/R/server.R
@@ -70,7 +70,10 @@
 #' @param tools Optional collection of tools to expose. Supply either a list
 #'   of objects created by [ellmer::tool()] or a path to an `.R` file that,
 #'   when sourced, yields such a list. Defaults to `NULL`, which serves only
-#'   the built-in session tools when `session_tools` is `TRUE`.
+#'   the built-in session tools when `session_tools` is `TRUE`. Note that
+#'   **tools are associated with the `mcp_server()`** rather than with
+#'   `mcp_session()`s; to determine what tools are available in a session,
+#'   set the `tools` argument to `mcp_server()`.
 #' @param ... Reserved for future use; currently ignored.
 #' @param type Transport type: `"stdio"` for standard input/output (default),
 #'   or `"http"` for HTTP-based transport.
@@ -81,7 +84,8 @@
 #'   for stdio transport.
 #' @param session_tools Logical value whether to include the built-in session
 #'   tools (`list_r_sessions`, `select_r_session`) that work with
-#'   `mcp_session()`. Defaults to `TRUE`.
+#'   `mcp_session()`. Defaults to `TRUE`. Note that the tools to interface with
+#'   sessions are still first routed through the `mcp_server()`.
 #'
 #' @returns
 #' `mcp_server()` and `mcp_session()` are both called primarily for their
diff --git a/man/server.Rd b/man/server.Rd
diff --git a/vignettes/server.Rmd b/vignettes/server.Rmd
@@ -35,9 +35,9 @@ knitr::include_graphics("https://raw.githubusercontent.com/posit-dev/mcptools/ma
 
 -   **Clients** are the apps you'd like to connect an R session to, like Claude Desktop of Claude Code. mcptools supports any client that supports MCP.
 
--   Clients can run R functions as tools using an MCP **server**. Each client that supports MCP will provide some entry point to configure a command and any additional arguments with the client. mcptools's command and arguments are `Rscript` and `-e "mcptools::mcp_server()"`. Different clients register this command in different ways. For example, to use mcptools with the client Claude Code, you might write `claude mcp add -s "user" r-mcptools -- Rscript -e "mcptools::mcp_server()"`.
+-   Clients can run R functions as tools using an MCP **server**. Each client that supports MCP will provide some entry point to configure a command and any additional arguments with the client. mcptools's command and arguments are `Rscript` and `-e "mcptools::mcp_server()"`. Different clients register this command in different ways. For example, to use mcptools with the client Claude Code, you might write `claude mcp add -s "user" r-mcptools -- Rscript -e "mcptools::mcp_server()"`. Note, however, that `mcp_server()` on its own won't surface any tools that are useful for coding agents&mdash;instead, you need to provide `tools` to the MCP server. See [btw::btw_mcp_server()](https://posit-dev.github.io/btw/reference/mcp.html) for a server that surfaces useful tools.
 
--   **Sessions** are the R sessions that the client ultimately talks to. So, if you have an RStudio or Positron window open, those applications automatically start up an R session that the client could potentially talk to. To "opt in" your R sessions to be discovered by clients, run the R code `mcptools::mcp_session()`. You might want to run this code every time you start up R; to do so, add `mcptools::mcp_session()` to your `.Rprofile`, perhaps by first calling `usethis::edit_r_profile()`. **Configuring sessions is not required**; if you choose not to do so, tools will be executed in the server itself.
+-   **Sessions** are the R sessions that the client ultimately talks to. So, if you have an RStudio or Positron window open, those applications automatically start up an R session that the client could potentially talk to. To "opt in" your R sessions to be discovered by clients, run the R code `mcptools::mcp_session()`. You might want to run this code every time you start up R; to do so, add `mcptools::mcp_session()` to your `.Rprofile`, perhaps by first calling `usethis::edit_r_profile()`. **Configuring sessions is not required**; if you choose not to do so, tools will be executed in the server itself. Note that **tools are configured per-server rather than per-session**; to configure tools with a session, set the `tools` argument in `mcp_server()`.
 
 (In case this caught your eye: yes, the server is itself an R session. In mcptools's documentation, we'll always refer to the server R session just as the server; the fact that it's implemented in R is only a technical detail.)
 
