> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bily.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Resolve MCP connection and execution issues

> Restore a Bily MCP connection, correct its scope, and recover safely from search or execution errors.

<AccordionGroup>
  <Accordion title="Connect to the correct endpoint">
    Confirm that the URL is exactly `https://api-dispatcher.bily.ai/mcp`. The client must support remote Streamable HTTP MCP servers.

    Do not use `https://app.bily.ai/mcp`, `llms.txt`, or `llms-full.txt` as the endpoint. Reload the client after you update its configuration.
  </Accordion>

  <Accordion title="Open the Bily Connect flow">
    Confirm that the client supports MCP OAuth discovery, Authorization Code with PKCE `S256`, refresh tokens, and the `mcp_access` scope.

    The MCP endpoint answers an unauthenticated request with the discovery challenge. Compatible clients follow that challenge automatically.

    If the client cannot complete the flow, use an access key fallback.
  </Accordion>

  <Accordion title="Replace a rejected credential (401)">
    A `401` means the credential is missing, invalid, expired, or revoked. Reconnect through Bily Connect or replace the fallback key.

    Do not send a Bily Connect credential and `x-api-key` together.
  </Accordion>

  <Accordion title="Reconnect after another sign-in prompt">
    Reconnect through Bily Connect. Bily rotates refresh credentials for security.

    Reusing an older refresh credential or losing the latest refresh response can invalidate the connection.

    Do not paste credentials into the client or keep retrying an older credential.
  </Accordion>

  <Accordion title="Correct an out-of-scope request (403)">
    A `403` means the connection is authenticated, but the requested organization, store, permission, or action is outside its allowed scope.

    With Bily Connect, confirm that the signed-in user still belongs to the organization that owns the store.

    With a fallback key, use only the default store and organization recorded when the key was created.

    If the response requires store scope, select the intended store and create a replacement key under **Settings > MCP**.
  </Accordion>

  <Accordion title="Improve an empty search result">
    Describe the outcome, resource, and intended read or write. Add an accessible `storeUrl` when the request depends on connected store operations.

    Set `limit` from 1 to 20.

    Do not guess a helper name when `search` does not return it.
  </Accordion>

  <Accordion title="Correct invalid execute code">
    Pass a string that contains an async arrow function:

    ```javascript theme={null}
    async () => {
      return bily.context();
    }
    ```

    Keep the code at or below 20,000 characters. Return JSON-serializable data.
  </Accordion>

  <Accordion title="Shorten a timed-out execution">
    One execution can run for at most 20 seconds. Split broad work into smaller calls. Reduce query ranges or result limits, and return only the fields needed for the next decision.
  </Accordion>

  <Accordion title="Review a write before approval">
    Approval is expected for write, spend-affecting, and destructive operations. Review the function, store, proposed changes, planning metadata, and verification step in the client.

    Bily's planning metadata does not replace the client approval prompt.
  </Accordion>

  <Accordion title="Recover missing result data">
    Use `search` again. Review the operation's preconditions, input schema, verification guidance, and connected-store requirements.

    Confirm that dates are real calendar dates and the requested store is correct.
  </Accordion>
</AccordionGroup>

## Send safe diagnostic details to support

Record the client name and version, safe error message, timestamp, tool name, and store URL. Remove credentials and customer payloads before you contact [Bily support](mailto:support@bily.ai).