PRACTICAL FIELD GUIDE
MCP tool call timed out: check whether it worked before retrying
A timed-out tool call may have completed on the server even if the client did not receive its response. Inspect the intended resource before submitting the same mutation again.
MCPBackend editorial team · · Examples are illustrative
The short answer
An MCP timeout means the client stopped waiting, not that the server stopped working. The tool call may have finished after the client gave up. For a read-only tool, simply call it again. For a tool that changes something, read the current state first and retry only if the change is missing.
With MCPBackend: after a timed-out create_table or add_column, call get_schema. After create_project, call list_projects. If the table, column or project is already there, the first call worked and there is nothing to retry.
Which MCPBackend tools are safe to repeat
- Safe to repeat (read-only): list_projects, get_project, get_project_api, get_schema, get_usage and list_team_members. They are marked readOnlyHint in the tool list.
- Safe to repeat (they set a value): set_table_rls and set_auth_enabled. Running them twice leaves the same end state.
- Refuse a duplicate: create_table returns 409 table_exists and add_column returns 409 column_exists. After a timeout, that 409 means the first call succeeded.
- Create a duplicate: create_project makes a second project (or fails with plan_limit on the free plan's single project), create_api_key mints another key, and create_webhook adds a second subscription, so every event is delivered twice. Check before retrying these, and delete any extra.
Check, then retry
- Note what timed out: the tool, the project ID and the name of the table, column, key or webhook.
- Read the state with a read-only tool (get_schema, list_projects or get_project).
- If the change is there, carry on. If it is partly there (a table without the index you asked for, say), make only the missing change.
- If it is not there, retry once and read the state again.
A rule to give your coding agent
Agents tend to retry a failed call straight away. Put a rule like this in your project instructions (CLAUDE.md, AGENTS.md or Cursor rules):
When an MCPBackend tool call times out or errors without a clear result:
1. Do not repeat a create_* call straight away.
2. Call get_schema (tables, columns) or list_projects (projects) and check
whether the change already exists.
3. Treat 409 table_exists or column_exists after a retry as success.
4. Retry at most once, then report what you found.Why tool calls time out
Most MCP clients put a limit on how long they wait for one tool call, and slow networks or a slow operation can pass it. create_project is the slowest MCPBackend tool because it provisions a new database. Some clients let you raise the limit; Claude Code, for example, reads an MCP_TOOL_TIMEOUT environment variable in milliseconds. Check your client's documentation. A longer limit means fewer ambiguous results, but the check-then-retry rule still applies.
Put it into practice
- Record the operation, target project and requested resource name.
- Read the current schema or project state to determine whether the change exists.
- Retry only after resolving the uncertainty, and verify the resulting state once rather than issuing repeated duplicate requests.
What this looks like
ILLUSTRATIVE EXAMPLE
A create-table call times out after the table was created. A second create attempt fails because the name already exists, obscuring the original success.
A boundary to keep clear
A timeout is not a rollback guarantee. Treat mutation retries differently from harmless discovery requests.
Read next
MCPBackend context
MCPBackend's remote MCP server manages supported project configuration through your authorized account. Your running app uses the separate data API. A successful connection does not prove every tool call succeeded: inspect tool results, verify the project identity and read the current schema before a change.
Take the next step
Inspect the current project contract, try the change with disposable data, and verify the result through the same credentials your app will use. Record the expected response and one denied-access case before release.
Frequently asked questions
Did my MCP tool call run if it timed out?
Maybe. A timeout only tells you the client stopped waiting. Read the current state with a read-only tool before deciding whether to retry.
Is a 409 table_exists after a retry an error?
No. It means the first create_table call succeeded before the timeout. Call get_schema to confirm the columns and indexes match what you asked for.
Will retrying create_project make two projects?
It can. Each create_project call makes a new project. Call list_projects first; on the free plan a second project is refused with plan_limit.
How do I raise the MCP tool timeout?
It is a client setting, not a server one. In Claude Code set the MCP_TOOL_TIMEOUT environment variable (milliseconds); other clients document their own setting.
Sources and further reading
These references explain the underlying protocols and design principles. For supported MCPBackend operations and exact request shapes, inspect your project’s generated API contract.