MCP Client

View as Markdown

A RocketRide tool node that connects to an external Model Context Protocol server and exposes its tools to AI agents.

About Model Context Protocol

Model Context Protocol is a protocol for connecting AI applications to tools and data sources. MCP servers publish their available tools and accept calls using the protocol; this node makes those published tools available in a RocketRide agent.

What it does

Connects to an MCP server over one of three transports (STDIO (local subprocess), Streamable HTTP, or legacy HTTP+SSE), performs the MCP initialize handshake, discovers the server's tools via tools/list when the pipeline starts, and exposes them to agent nodes. Agents then discover and invoke these tools during their reasoning loop; each call is forwarded to the server as tools/call and the raw MCP result is returned.

This node has no pipeline lanes: it is a control-plane tool node, connected to agents via the tools invoke channel.

As a tool

The node registers exactly the tools returned by the connected server. Each tool is named <serverName>.<toolName>; serverName defaults to mcp (or to the node catalog name when present). The argument schema and returned value are the discovered server contract. Malformed input, an unknown namespace, a disconnected client, or a server failure raises an error rather than looking like an empty result.

Tools are namespaced as serverName.toolName (e.g. mcp.search_docs), where serverName is set in configuration. Tools are discovered at pipeline startup and cached, and the cache is re-read from the server whenever an agent discovers its tools or asks for a tool the cache does not know (at most once per second), so a server that adds or renames tools while the pipeline runs is picked up without a restart. A changed catalog is reported as a pipeline warning naming the added and removed tools. A tool that is still unknown after that refresh is refused with an explicit ToolUnavailableError and is never sent to the server, so an agent sees a clear failure rather than a plausible-looking answer.

The implementation is pure Python standard library (subprocess, urllib, JSON-RPC 2.0), no MCP SDK dependency and no extra packages to install. Each request has a 20-second timeout.

---

Profiles

The directory registers two services and each keeps its own default: MCP Client defaults to RocketRide MCP server (stdio) (RocketRide), and the Butterbase MCP Client preset to Butterbase MCP server (butterbase). Both are marked below; which one applies depends on the service you added to the pipeline.

Profile	Transport	Notes
RocketRide MCP server (stdio) (default)	stdio	Launches python -m rocketride_mcp
Generic MCP server (Streamable HTTP)	streamable-http	Enter endpoint URL
Generic MCP server (legacy HTTP+SSE)	sse	Enter SSE endpoint URL
Butterbase MCP server (default)	streamable-http	Branded Butterbase preset

Configuration

Choose the transport first, then provide only the connection values it uses. The default profile starts the RocketRide MCP server over STDIO; use an HTTP profile when the server runs elsewhere.

Server name

The server name controls the agent-visible <serverName>.<toolName> prefix. Leave the default mcp when one MCP server is attached, and choose a distinct name when an agent has tools from multiple MCP Client nodes so their names do not collide.

STDIO transport

Launches a local subprocess as the MCP server and speaks JSON-RPC over its stdin/stdout. The subprocess inherits the engine's environment (with PYTHONUNBUFFERED=1 set).

Older configs that used separate command + args fields are still accepted for backwards compatibility.

Streamable HTTP transport

Connects to a modern Streamable HTTP MCP endpoint (spec 2025-03-26 transport). Handles both plain-JSON and SSE-streamed responses, tracks the Mcp-Session-Id returned by the server, and sends a best-effort DELETE to terminate the session when the pipeline stops.

Legacy HTTP+SSE transport

Connects to an older two-channel MCP server: a long-lived SSE GET stream for responses (read on a background thread) plus an endpoint event that supplies the session-specific POST URL for requests.

Configuration is validated at save time: commandLine is required for stdio, endpoint for streamable-http, and sse_endpoint for sse.

---

Authentication

For the HTTP transports (streamable-http and sse), set bearer to send an Authorization: Bearer <token> header on every request. The token is stored encrypted and masked in the UI. Arbitrary additional headers (e.g. API-key headers) can be supplied via headers; a bearer value overrides any Authorization key in headers.

The STDIO transport has no authentication fields: the subprocess runs locally with the engine's environment.

---

Notes

Butterbase preset

services.butterbase.json in this directory defines Butterbase MCP Client, a branded preset that reuses this node's implementation (not a separate node). It pins the transport to streamable-http with endpoint https://api.butterbase.ai/mcp, namespaces tools as butterbase.<tool> (e.g. butterbase.init_app), and surfaces the bearer field as a Butterbase API key (bb_sk_..., created in the Butterbase dashboard). Prerequisite: enable Developer Mode on your Butterbase app so the agent can create and modify resources.

---

Runtime behavior

• Protocol versions advertised during initialize: 2024-11-05 for STDIO, 2025-11-25 for Streamable HTTP and SSE.
• Tool calls must use the fully namespaced server.tool form; a call addressed to a different serverName than this node's is rejected.
• The MCP server process/connection is started in beginGlobal and shut down in endGlobal; a failed handshake or tool discovery fails pipeline startup with a warning.

---

Zero-argument tools

Some MCP tools take no arguments (their input schema is empty). Strict reasoning-model agents can silently drop such a tool from their catalog when it is advertised with an empty JSON Schema. To keep these tools usable everywhere, the client normalizes an empty input schema to carry a single optional placeholder argument (rr_no_args) before presenting the tool to an agent. RocketRide records which cached tools received that synthesized placeholder and strips it only for those tools before the call, so the MCP server never receives it. A tool that genuinely declares an argument named rr_no_args continues to receive that argument unchanged.

---

Upstream docs

• Model Context Protocol specification
• Butterbase documentation

---

Schema

Butterbase MCP Client (services.butterbase.json)

Field	Type	Description	Default
mcp_client.bearer	string	API Key Butterbase API key (bb_sk_...). Create one in the Butterbase dashboard: dashboard.butterbase.ai → API Keys. Sent as an Authorization Bearer token.	""
mcp_client.endpoint	string	Endpoint Butterbase MCP Streamable HTTP endpoint. Defaults to the production server.	"https://api.butterbase.ai/mcp"
mcp_client.serverName	string	Server name Namespace prefix for the discovered tools: . (example: butterbase.init_app).	"butterbase"

MCP Client (services.json)

Field	Type	Description	Default
mcp_client.bearer	string	Bearer token Optional Authorization bearer token	""
mcp_client.commandLine	string	Command line Command line to launch MCP server (stdio transport). Example: python -m rocketride_mcp	"python -m rocketride_mcp"
mcp_client.endpoint	string	Endpoint MCP Streamable HTTP endpoint URL. Example: http(s)://host:port/mcp	""
mcp_client.headers	object	Headers Extra HTTP headers for streamable-http/sse transports	{}
mcp_client.serverName	string	Server name Namespace prefix for tools: . (example: local.echo)	"mcp"
mcp_client.sse_endpoint	string	SSE endpoint (legacy) Legacy MCP SSE URL (old transport). Example: http://127.0.0.1:8000/sse	""
mcp_client.transport	string	Transport How to connect to the MCP server	"streamable-http"