Hosted Zones and MCP troubleshooting

Hosted Zones let eligible Pro organizations place private workspace data on a self-hosted Leaf data plane. Usable Cloud continues to own organization, tier, and workspace-registry metadata. This boundary changes where MCP data operations run.

The behavior here is anchored to the released Usable v1.198.1 Hosted Zone surface.

Cloud and Leaf routing

For a Cloud workspace, connect to the normal endpoint:

https://usable.dev/api/mcp

For a workspace placed on a Hosted Zone, connect to the registered Leaf endpoint for private workspace data operations. Do not retry a Leaf-required operation against Cloud.

Leaf-local operations

The following tool families route to the Leaf data plane for a Leaf-backed workspace:

• fragment search, list, read, create, and update;
• fragment type lookup;
• collections;
• manual symlinks.

This keeps private fragment content and search within the configured data plane.

Cloud-proxied operations

The Leaf MCP forward proxy routes Cloud-owned actions such as:

• listing, creating, and updating workspace registry records;
• public workspace discovery and subscription;
• application management;
• organization and placement-related administration exposed by the current tools.

The client can keep the Usable tool vocabulary, but it must use the correct endpoint for the workspace data it is operating on.

Hosted Zone V1 file limit

File upload, search, retrieval, and attachment workflows are not supported for Leaf-backed Hosted Zone V1 workspaces. Use a Cloud workspace for file payload workflows until support is released.

A Cloud response with a typed HOSTED_ZONE_REQUIRED error is a routing instruction. Use its approved Hosted Zone metadata to select the correct Leaf endpoint; do not invent an endpoint from workspace content.

Diagnose by layer

401: authentication required

The OAuth session or token is absent, expired, malformed, or revoked.

• Reauthenticate through the client.
• Confirm the MCP URL and transport.
• For PAT clients, verify the secret store and rotate a suspected credential.
• Never replace a failed credential with a non-expiring browser token.

403: permission denied

Authentication succeeded, but the identity, workspace role, token scope, or tool capability does not allow the action.

Confirm the target workspace and required action. Do not automatically broaden access.

404 or missing object

The ID can be wrong, the object can be inactive, or the access boundary can intentionally hide it. List accessible workspaces or collections and resolve IDs again.

Empty or filtered tool list

Call tools/list directly with the same connection. Check:

• production versus stale host;
• standard /api/mcp versus ?openai=true mode;
• client filtering of unsupported schemas;
• OAuth completion;
• current client support for Streamable HTTP.

Use the raw response as the server source of truth.

Parse tool-level errors

Since v1.192.1, a tools/call can return HTTP 200 and a successful JSON-RPC envelope while the tool result has:

{
  "isError": true,
  "content": [
    { "type": "text", "text": "Fragment type ... not found in workspace" }
  ]
}

This is a domain failure, not a transport outage. Correct the request instead of retrying unchanged.

For fragment type failures:

1. Call get-fragment-types for the exact target workspace.
2. Select a valid returned type ID.
3. Retry once with corrected input.
4. Ask a workspace administrator to restore defaults if no usable type exists.

Unknown tools, malformed protocol requests, and unauthenticated calls can still be JSON-RPC errors.

Processing and ambiguous timeouts

Fragment creation, enrichment, uploads, and projections can be asynchronous. A result marked processing may be accepted but not immediately searchable.

After a timeout or processing response:

• fetch by returned ID if available;
• search for the stable key or exact title before retrying;
• use bounded backoff for read-only projection checks;
• avoid duplicate creates.

Client and schema compatibility

If one client fails while a direct call works:

• update the client;
• verify it supports the advertised protocol and Streamable HTTP;
• compare its displayed tools with tools/list;
• check whether it requires OpenAI-compatible aliases;
• reduce complex optional parameters for strict-schema clients;
• keep server and widget origins consistent where MCP app resources are rendered.

Widget domain or CSP metadata describes resource rendering. It is not an authentication or permission signal.

Search quality problems

If tools work but answers are poor:

• verify workspace scope;
• improve the query and search intent;
• add or remove tags;
• fetch full sources;
• prefer released evidence;
• report conflicts and context limits.

Do not debug retrieval quality by granting write or administrative permissions.

Incident response

If a token, OAuth grant, private source, or Leaf endpoint credential is exposed:

1. Revoke or rotate it.
2. Stop the affected client.
3. Review recent tool calls and mutations.
4. Remove public copies of sensitive material.
5. Narrow replacement permissions.
6. Follow your organization's incident process.

Related pages

• Connect an AI client to Usable
• MCP tools and permissions
• Search and ground agent answers
• Create and maintain knowledge safely