MCP Timeout Durations
This guide explains how long Carbon Arc MCP tool calls take, how the server keeps long-running calls alive, how to configure timeouts in your MCP client so requests aren't cut off early, and how OAuth session lifetimes work.
How long do tool calls take?
Carbon Arc MCP tools fall into two categories with very different runtimes:
| Category | Tools | Typical duration | Billing |
|---|---|---|---|
| Discovery | search_entities, search_insights, get_insights_from_entity, get_entities_from_insight, data_library, ontology, search_docs | Seconds | Free |
| Research & analysis | entity_research, acquire, target, forecast, upsell, retain, text_to_insight, framework_to_insight | 1–5+ minutes | Consumes tokens |
Discovery tools are read-only lookups and return quickly. Research and analysis tools orchestrate multi-step work — retrieving data, running analyses, and composing results — so they routinely run for several minutes. Broad or complex research questions can exceed five minutes.
How the server keeps long calls alive
You do not need to poll or reconnect during a long tool call. While a tool is running, the server streams progress events over the open connection:
- A keepalive progress event is sent roughly every 30 seconds for the entire duration of the call. This prevents intermediate proxies and network infrastructure from closing an idle connection.
- After about 5 minutes, progress events additionally signal that the query is unusually large, so clients can surface a "this is a big one, still working" notice to the user.
- Research tools also emit real progress updates (e.g. which analysis step is running) between keepalives.
The practical implication: as long as your client keeps the request open and doesn't enforce its own short timeout, the call will complete and return a result — even for long research queries.
Configuring your MCP client
Most MCP client libraries and hosts apply a per-request timeout on tool calls, and the defaults are often too short for research tools (60 seconds is a common default). Two settings matter:
1. Raise the tool-call timeout
Set your client's request timeout to at least 10 minutes if you plan to use research or analysis tools. Discovery-only integrations are fine with 60 seconds.
2. Reset the timeout on progress (recommended)
The official MCP SDKs support resetting the request timer whenever a progress notification arrives. Because Carbon Arc sends progress at least every 30 seconds, enabling this means the timeout only triggers if the connection actually goes silent — not just because a query is big.
Example with the TypeScript MCP SDK:
await client.callTool(
{ name: "entity_research", arguments: { user_query: "..." } },
undefined,
{
timeout: 60_000, // 60s of *silence* allowed
resetTimeoutOnProgress: true, // each progress event resets the timer
maxTotalTimeout: 1_800_000, // optional hard cap (30 min)
},
);
Example with the Python MCP SDK:
from datetime import timedelta
result = await session.call_tool(
"entity_research",
{"user_query": "..."},
read_timeout_seconds=timedelta(minutes=10),
)
Recommended settings by usage
| Usage | Timeout | Reset on progress |
|---|---|---|
| Discovery tools only | 60 seconds | Optional |
| Research & analysis tools | 10 minutes (or 60s silence window) | Yes |
| Automated pipelines / batch research | 30-minute total cap | Yes |
If your MCP host application (rather than your own code) manages the connection, check its settings for an MCP or tool-call timeout option and raise it accordingly.
OAuth connections and session lifetimes
Carbon Arc MCP connections are authorized with OAuth 2.0 (authorization code flow with PKCE). MCP clients that support the standard flow — including Claude Desktop, Cursor, and the official MCP SDKs — discover the endpoints, register, and complete the browser sign-in automatically when you first add the server. There are no API keys to manage.
Two durations matter for day-to-day use:
| Credential | Lifetime | What happens at expiry |
|---|---|---|
| Access token | 1 hour | Your client silently exchanges its refresh token for a new access token — no sign-in required |
| Refresh token | 30 days | A new browser sign-in is required to reconnect |
In practice:
- Active use is uninterrupted. As long as you use the connection at least once a month, the refresh cycle keeps the session alive indefinitely without re-authenticating.
- After 30+ days of inactivity, the connection expires. Your client will prompt you to sign in again (or show the server as disconnected until you reconnect it). This is expected — just re-authorize.
- Token expiry does not cancel an in-flight tool call. Authorization is checked when a call starts; a research call that runs past the hour mark completes normally. The refresh happens on your next request.
If your client doesn't refresh automatically (some early or custom MCP
integrations skip the refresh flow), you'll see authorization errors roughly
every hour. Request the offline_access scope when connecting and confirm
your client implements the refresh_token grant.
Troubleshooting
| Symptom | Likely cause | What to do |
|---|---|---|
| Research tool call fails after exactly 60s (or another round number) | Your client's default per-request timeout | Raise the timeout and/or enable reset-on-progress |
| Call drops mid-run with a connection error | Client or intermediate network closed the stream despite keepalives | Verify your client supports streaming (SSE) responses and isn't buffering; check corporate proxy idle limits |
| Call seems stuck with only periodic progress events | Normal for large research queries | Progress events roughly every 30 seconds mean the server is still working — let it finish |
| Repeated timeouts on the same query | Query scope may be very broad | Narrow the question (fewer entities, tighter timeframe) or split it into multiple smaller calls |
| Authorization errors roughly every hour | Client isn't refreshing its access token | Ensure the client requests offline_access and supports the refresh flow; reconnect the server if needed |
| "Invalid or expired refresh token" / prompted to sign in again | More than 30 days since the connection was last used | Re-authorize through the browser sign-in — no other action needed |
If a research call fails or times out and you're unsure whether it affected your token balance, contact support@carbonarc.co with the approximate time of the request.
Summary
- Discovery tools return in seconds; research tools take minutes by design.
- The server sends progress keepalives every ~30 seconds — long calls stay alive on the server side.
- Timeouts you hit are almost always client-side: raise your client's tool-call timeout to 10 minutes for research tools, and enable reset-on-progress if your SDK supports it.
- OAuth access tokens last 1 hour and refresh automatically; refresh tokens last 30 days, after which a quick browser re-authorization is needed.