{"record":{"id":"5ac9573f8d749106","repo":"vercel/ai","slug":"unknown-host-tool-relay-endpoint","errorCode":null,"errorMessage":"Unknown host tool relay endpoint.","messagePattern":"Unknown host tool relay endpoint\\.","errorType":"http","errorClass":"RelayRequestError","httpStatus":404,"severity":"warning","filePath":"packages/harness-acp/src/v1/bridge/host-tool-relay.ts","lineNumber":161,"sourceCode":"}\n\nasync function handleRequest({\n  request,\n  credential,\n  state,\n  serverName,\n  turn,\n  nextInvocationOrder,\n}: {\n  request: IncomingMessage;\n  credential: string;\n  state: CatalogState;\n  serverName: string;\n  turn: HostToolRelayTurn | undefined;\n  nextInvocationOrder: () => number;\n}): Promise<unknown> {\n  if (request.method !== 'POST') {\n    throw new RelayRequestError({\n      status: 404,\n      message: 'Unknown host tool relay endpoint.',\n    });\n  }\n  if (\n    !credentialsMatch({\n      expected: credential,\n      actual: request.headers.authorization,\n    })\n  ) {\n    throw new RelayRequestError({\n      status: 401,\n      message: 'Invalid host tool relay credential.',\n    });\n  }\n  const body = await readJSONBody({ request });\n  if (request.url === '/catalog/next') {\n    return handleCatalogNext({ body, state });","sourceCodeStart":143,"sourceCodeEnd":179,"githubUrl":"https://github.com/vercel/ai/blob/69428b1f8b037e4d118fb4853428d5c4e620493c/packages/harness-acp/src/v1/bridge/host-tool-relay.ts#L143-L179","documentation":"handleRequest rejects any HTTP request whose method is not POST with this 404 RelayRequestError. The relay only serves POST endpoints (/catalog/next, /catalog/seen, /invoke), so GET/PUT/DELETE requests to any path — including valid paths — are treated as unknown endpoints. It is surfaced to the client as a 404 JSON body with this message.","triggerScenarios":"Sending GET /invoke (e.g. opening the URL in a browser or curl without -X POST), a health-check probe hitting the relay URL with GET, or a misconfigured HTTP client using the wrong method against any relay path.","commonSituations":"Manually testing the relay URL in a browser; load balancer or health checks using GET on the MCP API handler route; SDK code or scripts using the wrong HTTP verb; proxying that strips or rewrites POST to GET on redirects.","solutions":["Send requests with method POST and a JSON body.","Verify the client library call you use issues POST (e.g. fetch with { method: 'POST' }).","Exclude the relay URL from GET-based health checks or add a dedicated POST-aware probe.","Check the exact request.url you are hitting; the relay only serves /catalog/next, /catalog/seen, and /invoke."],"exampleFix":"// before\nconst res = await fetch(relayUrl); // GET\n// after\nconst res = await fetch(relayUrl, {\n  method: 'POST',\n  headers: { authorization: `Bearer ${credential}`, 'content-type': 'application/json' },\n  body: JSON.stringify({ requestId, toolName, input, catalogRevision }),\n});","handlingStrategy":"validation","validationCode":"function assertPost(url: string, init: RequestInit) {\n  if ((init.method ?? 'GET').toUpperCase() !== 'POST') {\n    throw new Error(`Host tool relay requires POST, got ${init.method ?? 'GET'} for ${url}`);\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  const res = await fetch(relay.url, { method: 'POST', ... });\n  if (!res.ok) {\n    const { error } = await res.json();\n    throw new Error(`${res.status}: ${error}`);\n  }\n} catch (error) {\n  if (error instanceof Error && error.message.includes('Unknown host tool relay endpoint')) {\n    // fix HTTP method to POST and retry once\n  }\n}","preventionTips":["Never open the relay URL directly in a browser or with curl without -X POST.","Exclude relay endpoints from GET-based health checks.","Centralize relay HTTP calls in one helper that always sets method: 'POST'."],"tags":["http","relay","method-not-allowed","harness-acp"],"backgroundTag":"wrong-http-method","analyzedSha":"69428b1f8b037e4d118fb4853428d5c4e620493c","analyzedAt":"2026-08-30T12:32:21.016Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}