Remote Agent

Server integration

Private-network MCP pass-through proxy

Remote Agent installs an MCP-aware proxy on a server you control. Konrado.AI connects to the proxy with the Remote Agent API key, and each proxied request can include the target host and target token for the private MCP server behind it.

Use it when the real MCP endpoint is inside a private network, behind a firewall, reachable only from a jump host, or should be exposed through one stable Remote Agent URL.

What Is It?

Remote Agent is a network bridge for MCP servers that Konrado.AI cannot reach directly. It runs on a server you control, authenticates inbound MCP traffic, validates the requested target host when an allowlist is configured, optionally translates that target to an internal host:port, and forwards the request to the target server.

When a request does not include target headers, Remote Agent answers as its own local MCP service for basic agent status and maintenance context. When target headers are present, it acts as a pass-through proxy and does not reshape or merge the target server's data.

What It Can Do

Data Available To AI And Operators

What It Cannot Do

Security Model

Ticket Examples

Prerequisites

• Access to Konrado.AI Integrations.
• Root SSH access to the server where Konrado AI Remote Agent will run.
• The target MCP server host and token that Konrado.AI will send in request headers.
• Outbound network access from the remote server to the target MCP server.
• An available TCP port on the remote server. The default dashboard and proxy port is 8001.

Installation

In Konrado.AI, open Integrations > Applications, click Add Integration, and choose Remote Agent.

1. Log in to the Remote Agent server via SSH as the root user.
2. Copy the installation command from the Remote Agent modal.
3. Run the command in the SSH session.
4. Wait for automatic connection detection in Konrado.AI.

The generated command will look like this:

bash <(curl -s https://raw.githubusercontent.com/konradoai/proxy-downloader/main/init.sh) --api-key=YOUR_API_KEY --callback-url=https://app.konrado.ai/api/integrations/servers/install

Remote Agent uses the proxy-downloader installer and does not include a --platform argument.

The installer creates /opt/KonradoAiRemoteAgent, installs the KonradoAiRemoteAgent Python package, starts konrado-mcp-remote-agent.service, generates API_KEY, and registers the server callback with Konrado.AI.

Configure host routing after installation in the Remote Agent dashboard.

Open the Dashboard

The dashboard is available at:

http://<SERVER_IP>:8001/dashboard

If port 8001 is already in use, change SERVER_PORT in the Remote Agent configuration and restart the service. Make sure your firewall allows the selected port from the networks that need dashboard or proxy access.

The Logs tab shows recent requests, status codes, durations, whether requests passed or were blocked, target hosts, and the reason for blocked requests.

The Configuration tab edits the HOSTS runtime configuration saved in .env.

Configuration Fields

Remote Agent uses these .env fields:

Remote Agent no longer uses static target host or target token fields in .env. The target host and token must come from request headers when Konrado.AI wants to reach a private MCP server.

Each HOSTS entry can contain:

Example:

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

Request Headers

Konrado.AI authenticates to Remote Agent with:

Authorization: Bearer <API_KEY>

If a request does not include target headers, Remote Agent handles it locally. To proxy a request to a private MCP server, send both target headers:

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

Remote Agent forwards the request to:

http://<translated-target-host>/mcp

If the matching HOSTS entry has internalHost, Remote Agent connects to internalHost. Otherwise it connects directly to Target-Host. Sending only one target header is treated as an invalid proxied request.

Verify Success / Failure

The Konrado.AI dashboard will update from Waiting for connection... to Connected after the agent reports back.

You can also open the Remote Agent dashboard on the server and check that Konrado AI Remote Agent is running.

You can also verify the proxy directly:

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"}}}'

Troubleshooting

Installation Failure Commands

If Konrado.AI shows the integration as failed, first confirm the Remote Agent service is running and listening on the configured port.

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'

After the service restarts, open the Remote Agent dashboard and run Test Connection again in Konrado.AI.

Remove

Delete the Remote Agent integration in Konrado.AI, then uninstall the service from the remote server if it is no longer used.