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: MCP access has not been enabled for your company.
    • Fix: The company owner must enable MCP access in company settings or contact FITsociety support.
  • 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.

​
400 Write Idempotency Errors

  • COMPANY_MCP_IDEMPOTENCY_REQUIRED
    • Cause: A write call omitted its operation key.
    • Fix: Supply a unique idempotencyKey tool argument, or params._meta.idempotencyKey. Reuse the key only for an exact retry of the same requested change. If the tool schema lacks the argument, check the deployed server version and refresh the assistant’s tool discovery.
Company-owned nutrition and measurements do not require per-client dataAccessGrants. These grants are reserved for separately authorized external data sources such as future wearable integrations. An empty list from inspect_client_data_access does not mean the MCP connection’s health consent is missing. 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.
Expected tool rejections, including missing idempotency keys (400) and access denials (403), are recorded in this audit log without generating Sentry errors. Unexpected tool failures with status 500 or above are also passed to the backend’s Sentry reporter. MCP can return HTTP 200 with isError: true for a failed tool call, so HTTP status monitoring alone does not identify every failure.

​
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.