Remote Agent

Connect Konrado.AI to a target MCP server through Konrado AI Remote Agent on a remote server

Remote Agent installs a remote MCP proxy that receives MCP requests from Konrado.AI and forwards them to a target MCP server. Use it when the target MCP server is behind another host, private address, or access layer.

Estimated time: 15 minutes

Before You Start

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.

What This Connects

Konrado.AI sends MCP requests through Remote Agent to a target MCP server. The data Konrado.AI can read depends on the target MCP server.

Install Remote Agent

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

Remote Agent installation instructions

Log in to the Remote Agent server via SSH as the root user.
Copy the installation command from the Remote Agent modal.
Run the command in the SSH session.
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

Run the command as root. The script installs Konrado AI Remote Agent on the selected server and registers it with Konrado.AI.

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

Example:

http://46.62.152.33: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, and the reason for blocked requests.

Remote Agent dashboard logs tab

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

Remote Agent dashboard configuration tab

Configuration Fields

Remote Agent uses these .env fields:

Field	Description
`API_KEY`	Bearer token used by Konrado.AI to authenticate to the Remote Agent
`SERVER_BIND_IP_ADDRESS`	Address the Remote Agent listens on, usually `0.0.0.0`
`SERVER_PORT`	Port the Remote Agent listens on, usually `8001`
`HOSTS`	JSON array managed from the dashboard. Empty `HOSTS=[]` allows any `Target-Host`; non-empty `HOSTS` acts as an allowlist and optional routing map

Each HOSTS entry can contain:

Field	Description
`host`	Required host value accepted from the `Target-Host` request header
`internalHost`	Optional internal `host:port` that Remote Agent connects to when `Target-Host` matches `host`
`label`	Optional operator label, for example `DirectAdminResellers` or `cPanel EU clients`

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>

Send the target MCP server on each proxied request:

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.

Verify

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

Issue	What to check
Dashboard does not open	Confirm `konrado-mcp-remote-agent.service` is running and the selected port is reachable from your network
Proxy returns `400`	Confirm the request includes both `Target-Host` and `Target-Token` headers
Proxy returns `403`	Review `HOSTS` in the dashboard. If `HOSTS` is non-empty, the requested `Target-Host` must be listed
Private target is not reached	Verify the matching `HOSTS` entry uses the correct `internalHost`
MCP client tries `/register`	Disable OAuth in the MCP client or use custom headers/manual auth. Remote Agent expects direct MCP requests to `/mcp` or `/sse`

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.

Installation Failure Commands

On this page