xpipe-io/xpipe · error · BeaconClientException

No API endpoint found for path ${path}

Error message

No API endpoint found for path ${path}

What it means

The MCP callApi tool resolves the requested endpoint via BeaconInterface.byPath(path) and throws this BeaconClientException when no beacon interface is registered for that path. The path must exactly match a known HTTP API endpoint route.

Source

Thrown at app/src/main/java/io/xpipe/app/beacon/mcp/McpTools.java:88

                .build();
    }

    public static McpServerFeatures.SyncToolSpecification callApi() throws IOException {
        var tool = McpSchemaFiles.loadTool("call_api.json");
        return McpServerFeatures.SyncToolSpecification.builder()
                .tool(tool)
                .callHandler(McpToolHandler.of((req) -> {
                    var path = req.getStringArgument("path");
                    var payload = req.getRawRequest().arguments().get("payload");
                    var payloadJson = JacksonMapper.getDefault().valueToTree(payload);

                    if (!AppPrefs.get().enableHttpApi().get()) {
                        throw new BeaconClientException("HTTP API is not enabled");
                    }

                    var i = BeaconInterface.byPath(path);
                    if (i.isEmpty()) {
                        throw new BeaconClientException("No API endpoint found for path " + path);
                    }

                    var handshakeRequest = HandshakeExchange.Request.builder()
                            .client(BeaconClientInformation.Mcp.builder().build())
                            .auth(BeaconAuthMethod.ApiKey.builder()
                                    .key(AppPrefs.get().apiKey().get())
                                    .build())
                            .build();
                    var handshakeReq = HttpRequest.newBuilder()
                            .uri(URI.create(
                                    "http://localhost:" + AppBeaconServer.get().getPort() + "/handshake"))
                            .POST(HttpRequest.BodyPublishers.ofString(
                                    JacksonMapper.getDefault().writeValueAsString(handshakeRequest)))
                            .build();
                    var handshakeRes = HttpHelper.client().send(handshakeReq, HttpResponse.BodyHandlers.ofString());
                    var handshakeResJson = JacksonMapper.getDefault().readTree(handshakeRes.body());
                    if (handshakeRes.statusCode() >= 400) {
                        return McpSchema.CallToolResult.builder()

View on GitHub (pinned to d85ca821ba)

Solutions

1. Verify the exact endpoint path against the XPipe HTTP API documentation for the installed version
2. Match casing and prefixes exactly (BeaconInterface.byPath is an exact-path lookup)
3. Upgrade XPipe if the endpoint exists only in a newer release
4. Catch BeaconClientException and fall back to enumerating available endpoints or a dedicated MCP tool

Example fix

// before
{"path": "/api/v1/connection/list"} // wrong route
// after
{"path": "/connection/list"} // exact registered beacon path

// check the endpoint path before calling
const knownPaths = await listApiEndpoints(); // from installed-version docs or introspection
if (!knownPaths.includes(path)) {
  throw new Error(`unknown API path '${path}'; known: ${knownPaths.join(', ')}`);
}

try { return callApi(path, payload); } catch (BeaconClientException e) { if (e.message.startsWith('No API endpoint found for path')) { /* correct the path or fall back to a dedicated MCP tool */ } throw e; }

When it happens

Trigger: Calling the MCP 'callApi' tool with a 'path' argument that does not correspond to any registered BeaconInterface endpoint: typo, wrong API version prefix, or an endpoint that doesn't exist in this XPipe version.

Common situations: Copy-pasting endpoint paths from HTTP API docs with wrong casing or missing prefix; targeting endpoints added in newer XPipe versions than the installed one; guessing route names instead of listing them.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Category with id " + msg.getCategory() + " does not exist
• No connection found for input " + msg.getConnection()
• Missing argument for key " + key
• Invalid argument for key " + key
• No connection found for input " + name

AI-assisted analysis of xpipe-io/xpipe@d85ca821ba (2026-09-06). Data as JSON: /api/errors/8d3fda6533599b7c. Report an issue: GitHub.