Permissions and troubleshooting
Understand workspace access, read and write scopes, connection revocation, and common MCP errors.
Each MCP connection acts in one Fusial workspace. Permissions determine both which tools the assistant discovers and which operations it can complete.
OAuth access
OAuth access is the intersection of three sets of permissions:
- The scopes requested by the client.
- The scopes approved during workspace consent.
- The scopes allowed by your current workspace role.
Viewers have read-only access. Members can delegate supported writes, while admin-only scopes remain limited to owners and admins. A broader scope grant does not add capabilities the MCP server does not implement.
Membership and role are checked on each request. Removing a user from a workspace stops their OAuth access; changing their role can reduce the tools available to their connection. A promotion does not automatically add scopes that were never approved.
Workspace two-factor requirements and subscription access also apply to OAuth connections.
API-key access
API keys use the same scope vocabulary as the REST API. Keys are bound to the workspace where they were created, with a Read-only or Full access preset. Choose read-only for assistants that only need to research contracts and report on the portfolio.
Full-access keys enable supported MCP writes. They do not add document upload, deletion, member management, webhook management, or signature-sending tools.
Check effective permissions
Ask the assistant to call fusial_whoami. It reports the connected workspace
and effective scopes. If a tool is missing, compare those scopes with the
tool reference.
A visible tool can still require an additional scope for particular arguments.
For example, updating a title needs contracts:write, while changing a date
anchor also needs obligations:write. Including contracts in a counterparty
read requires contracts:read in addition to counterparties:read.
Revoke a connection
Open Settings → MCP in Fusial:
- Members can view and revoke their own OAuth connections.
- Workspace owners and admins can view and revoke any user's OAuth connection in that workspace.
Revocation removes the authorization and its tokens. The client must sign in and receive authorization again before it can continue.
API-key connections are managed separately. Revoke their key in Settings → API keys to stop access through that credential.
Troubleshooting
| Symptom or code | What to do |
|---|---|
| No tools appear | Check that the client uses Streamable HTTP and the /api/mcp URL, then finish authentication. Call fusial_whoami to inspect scopes. |
missing_credentials | Authenticate through OAuth or configure an API key in Authorization: Bearer … or x-api-key. |
invalid_token | Re-authenticate the OAuth connection. The token may be expired, revoked, replaced, or issued for another deployment. |
invalid_api_key | Check the configured key and replace it if it has expired or been revoked. |
authorization_revoked | Reconnect the assistant and approve access again. |
organization_not_authorized | Re-authorize for the intended workspace; an explicit workspace URL must match the OAuth grant. |
not_a_member | Ask a workspace admin to restore membership if access is still needed, then reconnect. |
two_factor_required | Enable two-factor authentication on your Fusial account, then reconnect. |
subscription_inactive | Have an admin restore the workspace's subscription. |
insufficient_scope or a missing write tool | Check fusial_whoami; use a connection with the required scopes, or omit optional related data that needs extra access. |
rate_limited | Wait for the returned retry interval before retrying. Semantic search also has AI usage limits. |
| A status transition is refused | Use the returned allowedNextStatuses; sending for signature requires the Fusial UI. |
invalid_owner | Use fusial_list_workspace_members to find an eligible owner. Viewers cannot own contracts. |
invalid_intake | Read the template's required fields and correct the per-field issues before generating the draft again. |
_truncation in a result | Request fewer items, narrow filters, or read smaller groups of sections. The result is not complete. |
Authentication failures can stop the HTTP connection. Errors within a tool call are returned as an MCP error result with a code, message, and, where available, details or a recovery hint. Use those details to correct the request.