Skip to main content
If your AI assistant is failing to execute tool calls or cannot list resources, this guide will help you resolve the issue.

​
MCP Error Codes Reference

The FITsociety MCP server uses standard JSON-RPC 2.0 error payloads when something goes wrong.

​
401 Unauthorized Errors

These errors mean the credentials provided are missing, invalid, or expired.
  • COMPANY_MCP_KEY_REQUIRED
    • Cause: The Authorization header is missing or does not start with Bearer .
    • Fix: Ensure the request contains Authorization: Bearer <your_key>.
  • COMPANY_MCP_KEY_INVALID
    • Cause: The provided static API key (prefix fsc_) was not found, is malformed, or does not match any active grant.
    • Fix: Re-check the key string or generate a new API key in the coach dashboard.
  • COMPANY_MCP_TOKEN_INVALID
    • Cause: The OAuth access token (prefix fsct_) has expired or was revoked.
    • Fix: Use the refresh token to request a new access token pair, or re-run the authorization flow.

​
403 Forbidden Errors

These errors occur when the credentials are valid but the request is rejected due to administrative settings or status checks.
  • COMPANY_MCP_FEATURE_DISABLED
    • Cause: The mcp feature flag has not been enabled for your company.
    • Fix: The company owner must enable the MCP feature flag in company feature settings.
  • COMPANY_MCP_GRANT_OWNER_INACTIVE
    • Cause: The coach account that created the API key or approved the OAuth connection has been demoted from Admin/Manager roles, deleted, or deactivated.
    • Fix: A current active Manager or Admin coach must recreate the API key or re-authorize the client application.
  • COMPANY_MCP_COMPANY_BLOCKED
    • Cause: The company has been administratively blocked by FITsociety.
    • Fix: Contact FITsociety support.
  • COMPANY_MCP_ACCESS_DENIED
    • Cause: The connection does not have permission to execute the requested tool. This occurs when:
      • The tool belongs to a module that was not authorized in allowedModules.
      • You are attempting a write operation (e.g., create_client), but the connection is in read-only mode or the tool is not in the allowedWriteTools list.
      • The tool requires Health Consent or Private Communication Consent, but the consent flag was not accepted during authorization.
    • Fix: Re-authorize the connection, making sure to tick the required modules, write tool toggles, and consent checkboxes.
These errors usually occur before the MCP client receives an OAuth access token.
  • COMPANY_MCP_CLIENT_GRANT_MODULES_INVALID
    • Cause: A client AI approval requested a company/coach module such as clients, client_notes, bookings, or invoices.
    • Fix: Request only explicit client AI modules such as client_ai_account, client_ai_bookings, client_ai_nutrition, or client_ai_messages.
  • COMPANY_MCP_CLIENT_AI_DISABLED
    • Cause: The request is for client MCP, but client AI access is disabled for the active client-company relationship, or the company no longer allows client AI access.
    • Fix: Enable client AI access for that client and company before approving or using client MCP. If the client portal offers a request-access action, sending that request should only notify the company; it must not create an MCP grant or issue OAuth tokens.
  • COMPANY_MCP_CLIENT_MCP_DISABLED
    • Cause: The request is for client MCP, but the company’s client MCP policy is disabled or has no allowed client modules.
    • Fix: A Manager or Admin must enable client MCP in company MCP settings and select at least one allowed client_ai_* module.
  • COMPANY_MCP_CLIENT_MCP_SCOPE_NOT_ALLOWED
    • Cause: An existing client MCP grant authenticated, but none of its granted modules are still allowed by the current company client MCP policy.
    • Fix: Update the company client MCP policy or ask the client to approve a new grant with currently allowed modules.
  • COMPANY_MCP_CLIENT_COMPANY_CONNECTION_REQUIRED
    • Cause: The authenticated client is not connected to the active company, or the relationship was removed, rejected, blocked, erased, or anonymized.
    • Fix: Reconnect the client to the company or choose a company where the client has an active relationship.

​
JSON-RPC Protocol Errors

  • -32601 (Method not found)
    • Cause: The method specified in the payload is not supported (e.g. not a valid MCP method or typo).
    • Fix: Verify the method string matches a supported action (like tools/list or tools/call).
  • -32600 (JSON-RPC batching is not supported / Invalid Request)
    • Cause: The payload format is incorrect or you sent an array of multiple JSON-RPC calls.
    • Fix: Send requests as single, individual JSON-RPC objects.

​
Troubleshooting Guide

​
1. Check the Audit Logs

FITsociety provides transparent logging for all connection activity.
  • Navigate to the coach dashboard under Settings > MCP Integrations > Audit Logs.
  • You can inspect a chronological list of all tool calls made by your assistant, the time they occurred, the duration, and any error code returned.

​
2. Tools Are Missing from tools/list

tools/list is filtered at runtime. If a tool is missing, check:
  • Whether the grant is a company/coach grant or a client AI grant.
  • Whether the tool’s module is present in allowedModules.
  • Whether a client AI grant requested only client_ai_* modules.
  • Whether client AI access is enabled for the client-company relationship.
  • Whether the module requires healthDataConsent or privateCommunicationConsent.
  • Whether the grant is read-only. Write tools appear only when readOnly is false and the exact tool name is present in allowedWriteTools.
  • Whether the company still has MCP enabled.
  • For company/coach grants, whether the grant owner still has active Manager/Admin access.

​
3. Verify Client Redirect URIs

If you encounter invalid_redirect_uri during the OAuth authorization handshake:
  • Ensure the redirect_uri parameter matches exactly (character-for-character) with one of the URIs specified during client registration.
  • Production OAuth clients must use HTTPS redirect URIs that exactly match the registered value.

​
4. Debugging PKCE

If the token exchange fails with invalid_grant or PKCE verification failed:
  • Double-check your PKCE SHA-256 generation.
  • Ensure you are encoding the digest using base64url encoding (no padding, + replaced with -, / replaced with _).
  • Make sure you pass the exact same redirect_uri to the authorization endpoint and the token endpoint.