Private Network Connector — Setup Guide

This guide explains how to connect an agent to a custom tool that lives on your private network — an internal REST API or MCP server that isn't reachable from the public internet.

A Private Network Connector is a lightweight connector you run inside your own network. It opens an outbound tunnel to Agentic Fabriq, so when your agent calls the Agentic Fabriq MCP server, requests for your private custom tools are routed back through that tunnel to your internal endpoint. Agentic Fabriq never needs direct (inbound) access to your network, and you don't open any firewall ports.

Table of Contents

• How it works
• Prerequisites
• Step 1 — Create the connector
• Step 2 — Enroll and run the connector inside your network
• Step 3 — Register the custom tool and assign the connector
• Step 4 — Register an agent and grant it the tool
• Step 5 — Connect the tool to the agent
• Managing connectors
• Troubleshooting
• Related guides

How it works

  Your private network                         Agentic Fabriq                 Your agent
 ┌───────────────────────┐                  ┌──────────────────┐           ┌──────────────┐
 │  Internal API / MCP    │   outbound wss   │   MCP server +   │   MCP     │  Your agent  │
 │  (not publicly         │◀─────tunnel─────▶│   gateway        │◀─────────▶│  (SDK)       │
 │   reachable)           │                  │                  │           │              │
 │        ▲               │                  └──────────────────┘           └──────────────┘
 │        │               │
 │   af-connector binary  │
 └───────────────────────┘
copy

• The connector runs next to your internal service and dials an outbound WebSocket tunnel to Agentic Fabriq (wss://dashboard.agenticfabriq.com/api/v1/connector/tunnel). No inbound ports are exposed.
• A custom tool (OpenAPI or MCP server) is registered in the dashboard and assigned to a connector. Tool calls for that integration are forwarded over the tunnel to your private endpoint.
• Running the connector inside your network is the only configuration you do on your side. Everything else (creating the connector, registering the tool, granting the agent access) happens in the dashboard.

Prerequisites

• Admin access to your workspace's Control Panel / Admin Console (personal workspaces call this admin area the "Control Panel"; team/paid orgs call it the "Admin Console").
• A host inside your private network that can run the connector (Docker is the typical runtime — see the connector repo's README) and can reach your internal API/MCP server.
• The custom tool you want to expose: an OpenAPI/REST API or an MCP server running on that private network.

Step 1 — Create the connector

1. Sign in to the dashboard: https://dashboard.agenticfabriq.com.
2. Open the sidebar and click Control Panel / Admin Console at the bottom.
3. Go to Private Network Connectors (/org/admin/network-connectors).
4. Click Add Connector, give it a name (and optional description), and click Create.
5. A one-time enrollment token is shown. Copy it now — it is displayed only once and cannot be retrieved after you dismiss the dialog.

A newly created connector shows Inactive until the connector binary connects from inside your network.

Step 2 — Enroll and run the connector inside your network

Get the connector source — it's linked from the dashboard ("Get the network connector") and also lives at https://github.com/agenticfabriq/network-connector.

1. Exchange the enrollment token for persistent credentials. Run this from inside your network:

curl -X POST https://dashboard.agenticfabriq.com/api/v1/connector/enroll \
  -H 'Content-Type: application/json' \
  -d '{"enrollment_token": "<ENROLLMENT_TOKEN>"}'
copy

The response contains the two values the connector needs to run:

{
  "connector_id": "2805af88-af30-4fb0-a599-764f0d747231",
  "agent_secret": "<CONNECTOR_AGENT_SECRET>"
}
copy

Save the connector_id and agent_secret securely (a secrets manager or env vars) — agent_secret authenticates the connector to the tunnel.

2. Build and run the connector, following the repo's README.md. You'll supply the two values from enrollment as CONNECTOR_ID and CONNECTOR_AGENT_SECRET. The run command looks like:

af-connector run \
  --af-host wss://dashboard.agenticfabriq.com \
  --connector-id <CONNECTOR_ID> \
  --agent-secret <CONNECTOR_AGENT_SECRET>
copy

Tip: You can point a coding agent (Claude Code, Cursor, Codex) at the repo and have it do the setup — e.g. "Follow README.md to build the container" — then provide CONNECTOR_ID and CONNECTOR_AGENT_SECRET for deployment.

3. Confirm it's connected. Back in Private Network Connectors, the connector's status should flip to Active and Last Seen should update. If it stays Inactive, see Troubleshooting.

Step 3 — Register the custom tool and assign the connector

1. In the Control Panel / Admin Console, go to Custom Integrations (/org/admin/custom-tools).
2. Click Add Integration and choose the type:
   • OpenAPI (REST API) — for an internal REST API.
   • MCP Server — for an internal MCP server.
3. In the Network Connector field, select the connector you created in Step 1. This is what routes the tool's traffic through your private network instead of the public internet.
4. Finish the setup for the tool:
   • OpenAPI: import your spec (from URL or file upload). Actions and scopes are auto-detected; review them, then click Complete Setup.
   • MCP Server: enter the server URL, discover auth requirements and tools, then complete setup.

By default, custom-tool actions follow a zero-trust model — they're denied until an admin grants them (which you do when registering the agent in the next step).

Step 4 — Register an agent and grant it the tool

1. Go to Agents in the Control Panel / Admin Console (/org/admin/apps) and click Add Agent.
2. Give the agent a name and pick a permission model (action-based is recommended for fine-grained control over what the agent can do).
3. Under Pick actions, select the custom tool you just created and choose the actions to grant the agent.
4. Click Register Agent, then copy the App ID (client ID) and Secret — the secret is shown only once. Your agent uses these credentials in its code to call the Agentic Fabriq MCP server.

See the Building an Agent guide for the agent code, and the General Agent Prompt to have a coding agent implement it for you.

Step 5 — Connect the tool to the agent

1. Open My Agents in the sidebar (/my-apps).
2. Click Manage on the agent you want to connect the private tool to.
3. Click Add Connection, select your custom tool, and tick the actions you want this connection to expose.
4. Click Create Connection. The tool now shows as connected for that agent.

That's it. When your agent calls the Agentic Fabriq MCP server, it can invoke this custom integration, and the requests are routed through your private network connector to your internal endpoint.

Managing connectors

From the Private Network Connectors page you can monitor and manage each connector:

• Status / Last Seen — Active means the connector binary is connected; Inactive means it isn't currently reachable.
• Rotate secret — issues a new agent_secret and invalidates the old one. Update your running connector with the new secret (it will need to reconnect).
• Revoke — blocks the connector from enrolling or connecting and closes its active tunnel.
• Delete — removes the connector and closes its tunnel. Any custom tools and agents that referenced it have their connector assignment cleared, so re-assign them to another connector if needed.

Troubleshooting

Symptom	Likely cause / fix
Connector stays Inactive	The connector binary isn't running or can't reach Agentic Fabriq. Confirm it's running with the correct CONNECTOR_ID and CONNECTOR_AGENT_SECRET, and that the host can make outbound connections to wss://dashboard.agenticfabriq.com.
Enrollment token error / token rejected	The enrollment token is one-time use and shown only once. If you lost it or it was already used, create a new connector to get a fresh token.
Tool call fails with "no connection" or permission errors	Make sure (a) the custom tool is assigned to the connector, (b) the agent was granted the action, and (c) you added the tool connection to the agent under My Agents.
Tool reachable publicly but you wanted it private	Confirm you selected the Network Connector when registering the custom tool — without it, the tool is treated as a public-network endpoint.

Related guides

• Custom Tools — registering OpenAPI / MCP-server integrations.
• Building an Agent — agent code that calls the MCP server.
• General Agent Prompt — drop-in prompt for Claude Code / Cursor / Codex.