xpipe-io/xpipe · error · BeaconClientException

HTTP API is not enabled

Error message

HTTP API is not enabled

What it means

The MCP callApi tool proxies requests to XPipe's HTTP API. Before dispatching, it checks the enableHttpApi preference and throws this BeaconClientException when the HTTP API is disabled in app settings. The MCP tool intentionally refuses to bypass that policy switch.

Source

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

                    return McpSchema.CallToolResult.builder()
                            .addTextContent(text)
                            .build();
                }))
                .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)))

View on GitHub (pinned to d85ca821ba)

Solutions

1. Enable the HTTP API in XPipe settings (Settings > HTTP API / enableHttpApi preference) and restart if needed
2. Set enableHttpApi=true in the prefs/config file for headless environments
3. If the HTTP API must stay off, use dedicated MCP tools instead of callApi
4. Catch BeaconClientException and instruct the user to enable the HTTP API

Example fix

// before
if (!AppPrefs.get().enableHttpApi().get()) { /* tool call fails */ }
// after: enable the setting first
AppPrefs.get().enableHttpApi().set(true); // or toggle in Settings UI

// check the setting before calling callApi
const httpApiEnabled = await getPref('enableHttpApi');
if (!httpApiEnabled) throw new Error('Enable the HTTP API in XPipe settings before using callApi');

try { return callApi(path, payload); } catch (BeaconClientException e) { if (e.message === 'HTTP API is not enabled') { /* guide the user to enable the setting */ } throw e; }

When it happens

Trigger: Calling the MCP 'callApi' tool while the AppPrefs.enableHttpApi setting is off (its default in many installs).

Common situations: Fresh XPipe installations where the HTTP API was never enabled; users who disabled the API for security after setup; headless/CI environments with a settings file that omits the option.

Related errors

• Missing argument for key " + key
• Invalid argument for key " + key
• No connection found for input " + name
• Multiple connections found: " + connectionPaths
• Connection ${path} is not a shell connection

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