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
Authorizationheader is missing or does not start withBearer. - Fix: Ensure the request contains
Authorization: Bearer <your_key>.
- Cause: The
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.
- Cause: The provided static API key (prefix
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.
- Cause: The OAuth access token (prefix
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 theallowedWriteToolslist. - The tool requires Health Consent or Private Communication Consent, but the consent flag was not accepted during authorization.
- The tool belongs to a module that was not authorized in
- Fix: Re-authorize the connection, making sure to tick the required modules, write tool toggles, and consent checkboxes.
- Cause: The connection does not have permission to execute the requested tool. This occurs when:
400 Write Idempotency Errors
COMPANY_MCP_IDEMPOTENCY_REQUIRED- Cause: A write call omitted its operation key.
- Fix: Supply a unique
idempotencyKeytool argument, orparams._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 useparams._meta.idempotencyKey.
inspect_client_data_access does not mean the MCP connection’s health consent
is missing.
400 Consent and Approval Errors
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, orinvoices. - Fix: Request only explicit client AI modules such as
client_ai_account,client_ai_bookings,client_ai_nutrition, orclient_ai_messages.
- Cause: A client AI approval requested a company/coach module such as
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-Afternumber of seconds, also returned aserror.data.retryAfterSeconds. Inspecterror.data.scope,limit,remaining, andwindowSecondsfor the applied quota. Pace requests usingRateLimit-RemainingandRateLimit-Reset; retries also consume allowance. Keep the sameidempotencyKeywhen 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
retryAfterMsduration in milliseconds, then retry the exact arguments with the sameidempotencyKey. 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 usematerialize_nutrition_daysfor up to 31 days per call. Keep date-specific adjustments onset_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.
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/listortools/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.
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
healthDataConsentorprivateCommunicationConsent. - Whether the grant is read-only. Write tools appear only when
readOnlyis false and the exact tool name is present inallowedWriteTools. - For company/coach grants, whether the grant owner still has active Manager/Admin access.
3. Verify Client Redirect URIs
If you encounterinvalid_redirect_uri during the OAuth authorization handshake:
- Ensure the
redirect_uriparameter 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 withinvalid_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_urito the authorization endpoint and the token endpoint.