A connection to one MCP server, owned by one agent. Use it instead of
tools_mcp() when you need a fixed list of allowed tools, resources and
prompts, a request timeout, or control over when the server stops. Each
connection runs its own mcptools client in a separate R process. Requires
mcptools 1.0.2 or 1.0.3.
Details
Create the Agent first, then the connection. The allowlists are fixed when
the connection is created; $discover() never adds to them. Register
$tools() on the agent so that calls go through its permissions, hooks and
limits. The other methods call the server directly, outside any agent run.
Methods that contact the server return promises. A connection handles one
request at a time; a second request made meanwhile errors, but other
connections are not blocked. Call $close() when the conversation ends.
$cancel(), and any request that times out, stop the connection and
discard the server's session state; its tools then stop working.
mcptools waits about 4 seconds for a stdio server's reply and doesn't match
replies to requests, so a late or mismatched reply fails the call with a
deputy_mcp_desynchronized error and closes the connection. Create a new
connection to continue.
The connection is tied to the agent's ID, session and run context: its tools can't be registered on another agent and stop working if the agent's session changes. Connections are not saved with the agent's session.
Methods
McpConnection$new()
Start the server and connect to it.
Usage
McpConnection$new(
config,
server,
agent,
tools = character(),
resources = character(),
prompts = character(),
timeout = 60,
startup_timeout = 60
)Arguments
configPath to an mcptools JSON configuration.
serverName of the server in
config.agentThe agent that owns the connection. The server starts in its working directory.
toolsNames of the server tools to allow. None by default. The connection fails if the server doesn't offer all of them.
resourcesResource URIs to allow. None by default.
promptsPrompt names to allow. None by default.
timeoutMaximum seconds for each request. A request that takes longer closes the connection.
startup_timeoutMaximum seconds for the client and server to start.
McpConnection$discover()
List one page of what the server offers. Listing an item doesn't allow it.
Usage
McpConnection$discover(
kind = c("tools", "resources", "resource_templates", "prompts"),
cursor = NULL
)McpConnection$get_prompt()
Get an allowed prompt. The prompt is not added to any conversation.
Usage
McpConnection$get_prompt(name, arguments = list())McpConnection$capability_tools()
Create <prefix>_read_resource and <prefix>_get_prompt
tools that let the model read allowed resources and get allowed
prompts. Each is created only if its allowlist isn't empty. Prompts
that need arguments can't be fetched this way.