Server endpoints

Site metadata, icons and domain-verification routes. These are separate from room communication.

Documentation, static resources and utility services. Availability depends on the deployed resource archives or classpath.

/docs, /showcase, /mcp and /mcp/showcase and /tncaptcha redirect to their trailing-slash forms. Java documentation is served under the singular /javadoc/ path when the documentation archive is available.

Operational endpoints for server health, logs and cache management. Access checks are specific to each route.

Routes used to load an app, obtain setup values and join its virtual room. The shared runtime handles setup and reconnection.

Load /assets/core/comms.js before app code and let rc.connect() load setup. Use setup values after rc.onConnected(). See the runtime and app development guide for room communication APIs.

The MCP endpoint requires no persistent protocol session. It uses JSON-RPC 2.0 and protocol version 2025-11-25. Room codes grant access to room operations; no account or bearer token is required. It does not enumerate rooms. The MCP interface and MCP information page explain browser control.

Request contract

• Send Content-Type: application/json and a JSON object, not a batch array. Requests need a string or numeric id. Notifications whose method starts with notifications/ receive 202 without executing tools.
• If supplied, MCP-Protocol-Version must be 2025-11-25. An Origin header must match the request scheme, host and port; requests without Origin are accepted.
• Both endpoints limit request bodies to 256 KiB and return Cache-Control: no-store. HTTP errors include 400 for invalid headers or callback data, 403 for a rejected Origin, 405 for non-POST requests, 413 for oversized bodies and 415 for a non-JSON content type.
• JSON-RPC parse, request, method and parameter errors use HTTP 200 with an error object (codes -32700, -32600, -32601 and -32602). Tool failures instead return result.isError: true.

Tools

The default execution timeout is 10,000 ms; timeout_ms accepts integers from 1 to 30,000. JavaScript and generated reply JSON are each limited to 65,536 characters. At most 64 executions can wait concurrently. Only the first reply or failure counts; returning from the function alone does not send a result. Asynchronous callbacks may reply later, but must catch their own errors.

Example JSON request bodies

POST each object separately to /api/mcp. Use a room with a connected browser and replace the example client ID with one returned by list_clients.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": {"name": "example-client", "version": "1.0"}
  }
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {"name": "list_clients", "arguments": {"room": "test-0001"}}
}

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "execute_javascript",
    "arguments": {
      "room": "test-0001",
      "client": "abcd2345",
      "javascript": "reply({title: document.title, url: location.href});",
      "timeout_ms": 10000
    }
  }
}

Named APIs use /api/proxy/{target}. The server supplies configured keys from api-keys.properties; unknown targets or missing required keys return 404 (API not available). Query parameters are forwarded for the data APIs below; the named OpenRouter and Gemini routes use fixed upstream paths. Cache durations describe the server's proxy cache.

For example, /api/basic-proxy/https://example.com/feed.xml places the full upstream URL after the route prefix. The table shows intended usage; the proxy forwards the incoming method and body on a cache miss. WebSocket upgrades are rejected. Cache entries are keyed by target URL; hits include X-Cache-Hit: true and X-Cache-Expiry.

Named API proxies remove incoming Cookie, User-Agent and Authorization headers before adding provider credentials (with the OpenRouter and Gemini model-list overrides described above). The basic and image proxies use the generic forwarding handler and do not apply this named-API header filtering.

Files are supplied by a browser in a room. These routes coordinate downloads and pending chunks; they are not persistent file storage.

Both prefixes share the same handler. For correctly structured paths, invalid room or client IDs return 400; an unavailable source client returns 503. The download can also include ?receiver={clientId} to identify the receiving client.

Responses depend on the selected handler and deployment configuration. The status alone does not prove that a browser action completed.

Routing and deployment

When encourageSecureConnections is enabled, application and API requests over HTTP redirect to HTTPS. API, file-relay and app requests pass through the request-rate check. Static documentation and information pages are routed before that check; well-known domain verification routes are handled before the HTTPS redirect.

Static resources, Javadoc archives and keyed APIs must exist in the deployment. A 404 from a named API can mean that the server lacks its configured key. Room operations, file transfers and MCP callbacks must reach the server instance holding the relevant connection or pending request.

Implementation sources

Java source paths below link to the corresponding API documentation.

• src/main/java/net/targetr/rc/RootResponder.java: route selection, redirects and static resources.
• src/main/java/net/targetr/rc/mcp/McpHandler.java: JSON-RPC requests, tool arguments, callback tokens and limits.
• src/main/java/net/targetr/rc/util/ApiProxy.java: named upstream routes, key requirements and cache durations.
• src/main/java/net/targetr/rc/client/ClientFileProxy.java: browser-hosted downloads, chunk uploads and range handling.