MCP troubleshooting

Start with the Python example. It calls TKP without a language model, which helps separate a connection problem from your agent's handling of tools.

Find the failed layer

A call can fail at three points:

1. HTTP: the client could not reach or authenticate to TKP. Check the HTTP status, such as 401 or 429.
2. MCP message: the response contains a JSON-RPC error, for example when the requested method is unknown.
3. Tool execution: the message contains a result, but that result has isError: true. The tool could not perform the operation; its content explains the failure.

HTTP 200 only confirms the HTTP request succeeded. Check the MCP message and tool result before using their data.

Connection and tool errors

Symptom	What to do
401	Check the bearer token, its expiry and whether it was revoked. For OAuth, refresh the token or sign in again.
403	Check that the credential has its MCP interface enabled. API access alone does not enable MCP.
No read tools or libraries	Grant read to at least one library. Upload and hint tools require separate permissions.
A tool is missing	Discover tools again after changing permissions. Follow every nextCursor returned by tools/list.
Item unavailable or inaccessible	Check the workspace, library permissions and exact ID. TKP deliberately does not reveal whether an inaccessible item exists.
Argument error	Compare the supplied arguments with the tool's inputSchema and correct them. Repeating an identical failed call will not fix it.
429	Wait for the response's Retry-After delay and reduce call frequency. The MCP limit is 60 requests per minute.
Connection or certificate error	Check that the URL is the TKP application's address plus /mcp. For local HTTPS, ensure the client trusts your development certificate.
HTML response	Check the URL and redirects. You may be reaching a browser login page instead of /mcp.
Upload succeeded but search is empty	Check the resource's ingestion status. It is searchable only after processing finishes successfully.
Signed upload returns 403 or 410	Check whether the URL expired or was already used. Send the original URL and file unchanged.
Retrieved media is not visible	Check your client's support for displaying MCP image, audio or file-link blocks. Receiving the blocks does not display them automatically.

Pending or failed resource questions

ask_resource starts a background job. Save its request_id and wait at least poll_after_seconds before calling get_resource_answer; repeated immediate polls only add load.

If the job fails, inspect its error, whether the error is retryable, and the reported coverage. A failed or cancelled job is not a completed answer. See the asynchronous question workflow for pending and terminal statuses.

Keep credentials, signed URLs and sensitive document contents out of logs when sharing diagnostics.