Developer Hub

Check, stop and recover local access

Test each layer of a local MCP setup, read common errors, rotate the key and stop every local piece safely.

Optional custom reference setup

This guide supports the reference starter (ZIP) used in Connect a raia agent to local tools. It is not a built-in raia feature; you run, check and stop every local piece yourself.

Test one layer at a time

When the agent says it "cannot use the tool", the cause can be in any of several layers. Check them in order so you know exactly where it breaks, instead of changing several things at once.

Layer	How to check	What you should see
Gateway	Is the `npm start` window open and free of errors?	Gateway running
Local tools and key	`npm run check` in the starter folder	File tools listed and `ACME LOCAL CONNECTION OK`
Tunnel	Is the `cloudflared` window running, and is its address the one saved in raia?	Same current address
Path	The saved URL ends in `/files/mcp`, `/browser/mcp` or `/coding/mcp`	Exact path for that integration
Discovery	Get Available Tools in the integration	Only the starter's tools for that path
Selection	Ticked tools in raia include the one the task needs	Needed tool ticked
Task	A known task, such as reading `connection-test.txt`	Exact expected text or exit code

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.

npm run check runs only on your PC, so it separates "my gateway works" from "the tunnel or raia settings are wrong".

What common errors mean

Symptom	Likely cause	What to do
`401`	Missing or wrong key, or the `Bearer` prefix is missing	Run `npm run copy-key` again and paste the full value into the credential field
`403`	The request came from a web page (it had an `Origin` header)	Expected protection; test from raia or with `npm run check`
`404`	Wrong path, such as `/mcp` instead of `/files/mcp`, or that endpoint is not enabled	Fix the path in the saved URL. For `/browser/mcp` or `/coding/mcp`, check running jobs first, then restart the gateway with `npm start -- --browser` or `npm start -- --browser --coding`
`405` or `401` when you open the URL in a browser	Normal: the gateway accepts MCP `POST` requests and offers no event stream (MCP transports)	Test through raia or `npm run check` instead
`502` from the tunnel	The tunnel runs but the gateway is stopped or crashed	Restart `npm start` and run `npm run check`
Address no longer works	Quick Tunnel addresses change every time `cloudflared` restarts	Start the tunnel, then update every integration that uses it
Everything stopped overnight	The PC slept or a window was closed	Wake the PC, restart gateway and tunnel, retest the known file
Browser will not start, profile in use	Another Chrome window is using the agent's `browser-profile`	Close that window and retry
Coding tools fail	Docker Desktop is not running or the container stopped	Start Docker Desktop, run `docker compose -f coding/compose.yaml up -d`, then `ps`
"Job limit reached"	Two jobs are already running	Check them with `command_status`, stop what you do not need
Job ID unknown	The gateway restarted and forgot its jobs	Inspect the container before rerunning work; an unknown job is not a successful one

Replace a key you think was exposed

If the key may have appeared in a screenshot, chat or shared file:

Stop access first: stop the gateway and the tunnel with Ctrl+C.
Have the owner replace the contents of .credentials/bridge-key.txt with a new random value. The starter does not include a rotation command, and npm run setup keeps an existing key on purpose.
Restart the gateway, run npm run copy-key, and update the credential in every integration you use (files, browser and coding). Any you forget will get 401.
Confirm the old key now gets 401 before you rely on the new setup.

Stop everything

Turning an integration off in raia stops the agent from calling it. It does not stop anything on your PC: running jobs, Chrome, the tunnel and the gateway keep going. Stop each piece in this order and check it:

Ask for command_stop on each known running job and confirm with command_status that it ended.
Stop the demo container:

powershell

docker compose -f coding/compose.yaml stop
docker compose -f coding/compose.yaml ps

Press Ctrl+C in the cloudflared window and in the gateway window.
Close the agent's Chrome window, and switch off the raia integrations you no longer want.

Stop only these named pieces. Do not delete the workspace, remove volumes or reset Docker to "fix" a connection error; you could lose the demo and unrelated work.

About always-on setups

A named Cloudflare tunnel gives you a stable hostname. Starting the gateway and tunnel automatically, and restarting them after a crash or reboot, is a separate job for a service you configure and supervise yourself. Both are convenience, not autonomy. It does not make an agent continue a task on its own, and it does not change how raia Loops run or fix a Loop that fails. Each conversation or Loop still needs tools that are reachable at that moment. Interactive email-code protection on a tunnel does not work for an MCP client, so it cannot replace the bearer key. After every update to the starter or its tools, recheck the tool lists and repeat one harmless task per endpoint.