Remote Agent

Developer tools

A relay to MCP servers inside your network

Remote Agent is a small relay you install on a server you control, inside your network. It checks every request against its API key. When a request names an internal MCP server you allow, the relay forwards it there. It logs what it did. One public address can then front several private MCP servers.

Konrado reaches a private server through the relay with a Custom MCP server connection that carries the target's name and token. The Remote Agent connection itself reaches only the relay's own tools today, and those give Konrado nothing to use.

How it works

The relay answers on /mcp and /sse. Every request needs its API key:

Authorization: Bearer <API_KEY>

A request with no target headers stays on the relay itself. A request that carries both target headers goes on to that MCP server:

Target-Host: <target-host>
Target-Token: <target-token>

The relay checks Target-Host against the HOSTS allowlist. It then connects to http://<host>/mcp, or to the host's internalHost, and sends Target-Token there as the bearer token. It passes on what the target answers, unchanged. The relay refuses a request with only one of the two headers.

What the relay can do

What Konrado cannot do

Before you start

• Root SSH access to the machine that runs the relay, with Python 3.10 or newer, curl, unzip and systemd.
• Outbound access from that machine to the target MCP servers.
• A free TCP port. The relay and its dashboard use 8001 unless you change it.
• Port 8001 open to Konrado's IP addresses (see the list).

Connect

bash <(curl -s https://repo.konrado.ai/remote-agent/init.sh) --api-key=YOUR_KEY --callback-url=https://app.konrado.ai/api/integrations/servers/install

Reach a private MCP server

For each private MCP server, add a Custom MCP server in Konrado that points at the relay.

Konrado sends the three headers with every request, and the relay forwards each request to the target. The target's tools then work like any custom MCP server's: Konrado takes only the ones marked readOnlyHint: true, and they are not tied to one customer's service. Read the Custom MCP server page for the details.

The relay serves plain HTTP, so the headers travel unencrypted. To encrypt them, put the relay behind your own HTTPS proxy and use its https:// address as the Server URL.

The dashboard

The Logs tab shows recent requests, status codes, durations, whether each passed or was blocked, the target host and why a request was blocked.

The Configuration tab edits HOSTS and saves it to the relay's .env file.

If you change SERVER_PORT later, restart the service and open the new port in your firewall. Konrado still calls the old address, so open the Remote Agent row in Konrado and change its Server URL to the new port.

Settings

The relay reads these from its .env file:

Each HOSTS entry can hold:

HOSTS='[
  {"host":"203.0.113.20:8000","label":"Direct target"},
  {"host":"konrado-test:8000","internalHost":"203.0.113.20:8000","label":"Alias through internalHost"}
]'

Check it works

The relay is on the Integrations page as Connected, with the type Remote Agent and its version. Konrado tests the connection again every hour. You can also check the relay itself:

curl http://<SERVER_IP>:8001/health

It answers {"status": "healthy", "service": "Konrado AI Remote Agent"}. To test a route, send an MCP request with both target headers:

curl -i -X POST http://<SERVER_IP>:8001/mcp \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Target-Host: <target-host>" \
  -H "Target-Token: <target-token>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

If something is wrong

systemctl status   konrado-mcp-remote-agent.service
journalctl         -u konrado-mcp-remote-agent.service --since "15 minutes ago" --no-pager
systemctl restart  konrado-mcp-remote-agent.service
ss -ltnp | grep ':8001'

Update the relay

When a new version is out, the row on the Integrations page shows Update to v…. Konrado cannot update the relay for you: click it, then run the command it shows on the relay's machine:

bash /opt/KonradoAiRemoteAgent/scripts/update.sh

Remove the integration

Open Workspace SettingsIntegrations, open the row menu (three dots) and choose Delete. Then, if nothing else uses the relay, remove it from its machine as root:

systemctl disable --now konrado-mcp-remote-agent.service
rm /etc/systemd/system/konrado-mcp-remote-agent.service
systemctl daemon-reload
rm -rf /opt/KonradoAiRemoteAgent
userdel konrado-mcp-remote-agent
groupdel konrado-mcp-remote-agent