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_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, refresh the assistant’s tool discovery or use params._meta.idempotencyKey.
Company-owned nutrition and measurements do not require per-client external-data grants. These grants are separate permissions for authorized external data sources. 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, use it to ask your coach or company admin to enable access, then retry the OAuth flow.
  • 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.

429 Query Budget and Temporary Tool Failures

  • COMPANY_MCP_RATE_LIMITED
    • Cause: The request allowance for the credential or IP address is exhausted. Defaults are 120 requests per minute per credential and 240 per IP, shared across tools and protocol requests. Configured limits are stated in MCP initialization/discovery instructions and the response headers.
    • Fix: Pause requests for the Retry-After number of seconds, also returned as error.data.retryAfterSeconds. Inspect error.data.scope, limit, remaining, and windowSeconds for the applied quota. Pace requests using RateLimit-Remaining and RateLimit-Reset; retries also consume allowance. Keep the same idempotencyKey when retrying an unchanged write.
  • COMPANY_MCP_QUERY_BUDGET_EXCEEDED
    • Cause: The connection has used its query budget for the current minute. The default budget is 120 units; each write costs 5 units. Reads also consume budget. Preparing a week with many individual items may span multiple windows.
    • Fix: Wait for the returned retryAfterMs duration in milliseconds, then retry the exact arguments with the same idempotencyKey. Resume from the rejected item; do not repeat already completed writes with new keys. When copying the same plan across dates, fill the base plan once and use materialize_nutrition_days for up to 31 days per call. Keep date-specific adjustments on set_nutrition_day_item.
  • COMPANY_MCP_CIRCUIT_OPEN
    • Cause: The tool is temporarily paused after repeated system failures.
    • Fix: Wait for retryAfterMs, then retry with the same arguments and key.
Query-budget and temporary tool rejections happen before a change starts and can be retried after the returned delay. A timeout or another error does not always mean nothing was saved. Keep the same key when retrying unchanged arguments and check the affected record before starting a new write. Completed writes return their saved result without applying the change again or consuming additional query budget.

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.
MCP can return HTTP 200 with isError: true for a failed tool call. Check the tool result and its error code as well as the HTTP status.

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