Home / Docs / Integrate against your own install

Integrate against your own install

The base URL, the token, the MCP server and the router endpoint of an install you run yourself, and what the golden run proves of each.

Use this page to point your tools at an install you run yourself. A self-hosted install (the community install) serves everything on one edge: replace https://control.massrelay.ai with your edge URL, for example https://massrelay.example.com, and the same calls work.

Find the base URL

The console endpoints are under <edge>/api, the router endpoints under <edge>/v1.

Note The router endpoint only exists when the install runs the router profile. Without it <edge>/v1 answers 502.

Get a token

Every /api endpoint takes a bearer token. In a self-hosted install the token is an access token from your own Keycloak realm massrelay, issued to a signed-in person. The golden run mints one for the demo user with the authorization-code flow on the client control and the client secret in your community.env. The token never appears in its output.

A router key (mrk_...) is for /v1 only and is made on the Keys page.

Run the MCP server

@massrelay/mr-mcp fronts the same /api over stdio. Set MASSRELAY_URL to your edge and MASSRELAY_TOKEN to the bearer, then start it from a checkout. The api image does not carry that build today, so build it first.

curl

npm run build -w packages/mr-mcp
MASSRELAY_URL=https://massrelay.example.com MASSRELAY_TOKEN=YOUR_TOKEN \
  node packages/mr-mcp/dist/bin.js

The golden run starts the server, lists the tools and calls rooms.list.

Register an MCP server of your own

POST /api/integrations/mcp takes a name and a URL. The URL passes the same server-side check as every outbound address: a loopback, private or link-local target is refused with a 400 whose message says the URL was refused, and nothing is registered. The install has no HTTP MCP service on its internal network yet, so the golden run proves the refusal, not a live registration.

Call the router endpoint

GET <edge>/v1/models with no key answers 401 invalid_api_key; send X-MassRelay-Client with your tool's name and version. With a router key the same call lists your models.

curl

curl https://massrelay.example.com/v1/models \
  -H "Authorization: Bearer $RELAY_KEY" \
  -H "X-MassRelay-Client: my-tool/1.0"

Check your install with the golden run

bash deploy/community/golden-run.sh ends with an integration section of three lines: mcp-client, mcp-registry and sdk-baseurl (a SKIP when the router profile is off).