Developer Hub

Connect a raia agent to local tools

Optional custom setup: reach tools on your PC through an authenticated HTTPS tunnel and a loopback MCP gateway, then verify a first file read.

Optional custom reference setup

This is an optional, guided reference setup for a Windows PC. It lets a raia agent read files in one demo folder on your PC; later guides add a dedicated browser and a demo coding container. Start with files, then add the browser or coding only when you need them. The starter is custom documentation code, not a built-in raia feature, an installer or a production service, and it comes with no production guarantee. Review the code before you run it. Your PC must stay awake and the windows described below must stay open.

What you are building

A raia agent runs in raia's cloud. If you type http://localhost into an MCP integration, "localhost" means raia's own server, not your PC, so the agent cannot reach anything on your machine that way. To let an agent use tools on your PC, you need a public, authenticated address that forwards to a small program on your PC.

text

raia CX agent
  └─ MCP Integrations skill (Authorization: Bearer <key>)
       │  https://<your-tunnel-host>/files/mcp
       ▼
cloudflared Quick Tunnel  (public HTTPS address → your PC)
       ▼
Starter gateway on 127.0.0.1:8939  (checks key, Origin, path, tool list)
       ├─ /files/mcp    → filesystem tools, workspace folder only
       ├─ /browser/mcp  → dedicated Chrome profile (optional)
       └─ /coding/mcp   → one demo Docker container (optional)

This diagram is an illustration of the local parts, not a raia screen.

The gateway and the tunnel do different jobs. The gateway is the program on your PC: it checks the key, refuses requests that come from a web page, and only offers the tools on its list. The tunnel only carries traffic from a public HTTPS address to the gateway. A tunnel is not authentication.

Most local MCP tools talk over their own console ("stdio") and have no network address. raia connects over HTTP, so the gateway translates between the two, following the MCP transports specification. That specification also asks local servers to listen only on loopback, check Origin and require authentication, which is what the starter does.

Before you start

You need	Why	When
Node.js 24 or newer, with npm	Runs the starter and its tools	Always
`cloudflared`	Creates the HTTPS tunnel (install from Cloudflare)	Always
A raia agent you are allowed to configure	Receives the new integration	Always
Google Chrome	Used by the browser endpoint	Only for browser control
Docker Desktop (Linux containers)	Runs the demo container	Only for the coding workspace

Step 1 — Download and check the starter

Download the reference starter (ZIP) and extract it somewhere you control, such as C:\raia-local-demo. The ZIP contains one top-level folder, raia-local-access-reference. Read README.md and the code. Then open PowerShell in that folder, the one that contains package.json, and run every command in these guides from there:

powershell

node --version
npm ci --ignore-scripts
npm test

node --version should print v24 or later. npm ci --ignore-scripts installs the exact versions in the lock file without running package scripts. npm test runs the starter's own checks; continue only if they pass.

Step 2 — Create the key and start the gateway

powershell

npm run setup
npm start

npm run setup creates a random private key in .credentials/bridge-key.txt, outside the workspace folder the agent can read, plus a fictional workspace/connection-test.txt. It keeps any files and key that already exist. Restrict the folder to your own Windows user.

npm start turns on only the files endpoint. Keep this window open: closing it stops access.

Step 3 — Check it on your PC first

In a second PowerShell window in the same folder:

powershell

npm run check

This local-only check should list the file tools and read ACME LOCAL CONNECTION OK from workspace/connection-test.txt. It never contacts a remote address. If it fails, fix it now; a tunnel would only hide the problem.

Step 4 — Start the tunnel

In a third window:

powershell

cloudflared tunnel --url http://127.0.0.1:8939

It prints a random public address ending in trycloudflare.com. Quick Tunnels are for testing: the address changes on every restart, there is no uptime guarantee, and they are not meant for production. Your endpoint is your own address followed by /files/mcp. Opening it in a browser may show 401 or 405; that is expected, because MCP uses POST.

Step 5 — Add the integration in raia CX

Open your agent's MCP Integrations skill and add a new integration, as shown in the MCP Integrations guide. Enter a Name such as Local_Files; names use only letters, numbers, underscores and hyphens, with no spaces. Put a human-readable explanation, such as "Reads the demo files on my PC", in the description so the model knows when to use it.

New Integration draft (fictional, unsaved): Name and Description.

Highlight 1: Name — letters, numbers, underscores and hyphens only; must start with a letter.
Highlight 2: Description — tell the agent when and why it should use these tools.

Paste your tunnel address with /files/mcp at the end and choose Streamable HTTP.

New Integration draft (fictional, unsaved): the MCP endpoint URL and Transport.

Highlight 1: URL — the provider's MCP endpoint. A valid URL reveals Get Available Tools.
Highlight 2: Transport — Streamable HTTP or SSE, as required by the server.

For the Authorization value, run npm run copy-key in the starter folder. It replaces your clipboard with the complete Bearer … value. Paste it only into the integration's credential field, then clear your clipboard. Never paste the key into a conversation, screenshot, ticket, shared files or source code.

Select Get Available Tools and tick only list_allowed_directories and read_text_file to begin.

The Get Available Tools button and its prerequisite note: tools must be loaded before the integration can be created.

Highlight 1: Get Available Tools — appears once the URL is valid.
Highlight 2: Prerequisite note — tools must be loaded before you can create the integration.

Step 6 — First task: read the known file

In a test conversation, ask: "List your allowed directory, then read connection-test.txt inside it and quote the contents exactly."

A good reply quotes ACME LOCAL CONNECTION OK. Check the actual tool result in the conversation, not only the agent's summary. If the agent paraphrases, invents text or says it has no access, work through Check, stop and recover local access.

What you are trusting

File text, and later browser content, screenshots and command output, travel through the tunnel provider and raia. Start with fictional demo files only.
Anyone with the address and the key can call every enabled tool while the gateway runs. The starter uses one key for all endpoints you enable.
Turning the integration off in raia does not stop anything on your PC. Stop the tunnel and gateway with Ctrl+C when you are done.

Next: Give the agent a dedicated browser or Give the agent an isolated coding workspace.