MCP servers

An MCP server running inside your own network — on an internal host, behind a VPN, on a private Kubernetes service — normally can’t be used from qRaptor, because the platform has no route to it.

Pointing the server at a remote executor solves that. Discovery, testing and every tool call travel through the executor, so qRaptor only ever needs to talk to the executor, and the executor talks to the MCP server locally.

Prerequisites

An executor showing Online, running somewhere that can reach the MCP server.
The MCP server’s URL as seen from the executor’s network, not from the internet.

Connect it

Start a new server

Agentic Workspace → Agent Tools → MCP Servers → New, and fill in the name, description and server URL as usual. See MCP for the general flow.

The URL is the one that resolves on the executor’s host — an internal DNS name or private IP is exactly right here.

Set Execution Location

Option	Effect
Auto (Platform decides)	Defers to the project default.
Local (Platform)	The platform connects to the server directly. Only works for a publicly reachable server.
Remote (Executor)	The executor connects to the server on qRaptor’s behalf.

The field explains itself in the UI: “Choose where MCP tools from this server will execute. Select “Remote” for servers only reachable from your infrastructure.”

The Execution Location selector on the new MCP server form

Choose the executor

Remote requires a Target Executor — unlike code nodes and tools, this one isn’t optional, because the server is reachable from a specific network and not just “somewhere remote”.

If none are running you’ll see “No remote executors registered. Add an executor in Project Settings → Executors.”

The Target Executor picker shown after selecting Remote execution

Discover the tools

Run discovery as normal. The request goes out through the executor, so the tool list you get back is the one the server actually exposes on your network — proof the path works before you save anything.

Test individual tools the same way. Both discovery and testing use the executor you selected.

After it’s connected

The server’s tools behave like any other MCP tools. Attach them to an agent’s skills, and they’ll show a REMOTE badge in the skills editor so it’s clear where they run.

Every call goes through the executor at runtime, including calls from deployed agents.

💡

Because the executor holds the network position, moving the MCP server later is mostly an executor question. If the server moves to a host the current executor can’t reach, point the server at a different executor rather than reconfiguring anything on the platform.

Common issues

Discovery times out — the executor’s host can’t reach the server URL. Check it from that host directly; internal DNS often resolves differently there than on your laptop.
You can’t save with Remote selected — a Target Executor is required for MCP servers. Pick one.
The picker is empty — no executors are online.
It worked at discovery but fails at runtime — the executor that discovered the tools isn’t the one online now, or the server moved. Re-check the pinned executor.

Manage executors — day-to-day operation.