Troubleshoot a Median MCP connection
Resolve sign-in, company access, unavailable reports, and request limits.
By Jacob Sheldon. Reviewed
Sign-in and permission errors
| Response | What it usually means | What to do |
|---|---|---|
| 401 Unauthorized | The request has no valid credential, or the session needs authorization. | Reconnect the client. Sign in to the Median account that has access to the company. |
| 403 Forbidden | The user or key is not authorized for the company or requested scope. | Check the signed-in user and company. For an MCP key, ask an owner or admin to review its access. Ask Median if the company is not available to that user. |
| Tool input error | A required argument is missing or a date is invalid. | Check the tool input table. Range reports need both from and to in YYYY-MM-DD format. |
A tool is missing
Refresh the MCP tool list in your client. The tools/list response shows what is available to the connection. If a report tool remains absent, ask Median whether it is enabled for your company and client.
A request returns 429
The current MCP limits are 30 requests per minute and 300 per hour per runtime instance. Bulk-read tools have an additional limit of 20 requests per minute per tool. Limits apply per runtime instance and may vary by deployment.
- Wait for the Retry-After interval when the response includes that header.
- Reduce polling and concurrent calls. For a large general-ledger read, use pagination instead of repeating the same request.
- Retry with backoff. Do not immediately repeat a request that received 429.
Disconnect or revoke access
OAuth access appears under Median Settings, Integrations, Connected apps. Choose Revoke beside the app. MCP keys appear in the MCP server card under Active connections; an owner or admin can revoke a key there. These controls are shown when enabled for your account. Removing an app or revoking a credential does not delete information the client already received.