MCP Timeouts & OAuth
This guide explains how long Carbon Arc MCP requests typically take, how long-running requests stay alive, how to configure your MCP client, and how OAuth session expiration works.
Tool Runtime Expectations
Carbon Arc MCP tools fall into three categories with different runtime expectations.
| Category | Tools | Typical Runtime | Billing |
|---|---|---|---|
| Discovery | search_entities, search_insights, get_insights_from_entity, get_entities_from_insight, data_library, ontology, get_filter_options, search_docs | Seconds | Free |
| Purchasing | text_to_insight, framework_to_insight | 0-2 minutes | Token usage |
| Research | entity_research, acquire, target, forecast, upsell, retain | 1-5+ minutes | Token usage |
Discovery tools are lightweight lookups and typically return within seconds.
Purchasing tools generate datasets and generally complete within a couple of minutes.
Research tools perform multi-step analysis across multiple datasets and routinely take several minutes to complete. Larger requests may take longer.
Long-Running Requests
You do not need to reconnect or poll while a request is running.
Carbon Arc automatically sends heartbeat events every 30 seconds during every MCP tool call. These keep the connection alive while work is in progress.
Heartbeats include:
- Elapsed execution time
- Tool name
- Long-running query indicator
After five minutes, the heartbeat marks the request as a long-running query so clients can surface additional status messaging.
Research tools also stream progress updates between heartbeats.
As long as your client keeps the connection open, the request will continue running until completion.
Configuring Your MCP Client
Most MCP clients apply a request timeout. The default is often too short for research workflows.
Increase Request Timeouts
For research workloads, configure your client to allow at least 10 minutes per request.
Discovery-only integrations can typically keep the default 60-second timeout.
Reset Timeouts on Progress
If your MCP SDK supports it, enable timeout resets whenever a progress event is received.
Since Carbon Arc sends heartbeat events every 30 seconds, this allows long-running requests to continue while still timing out if the connection truly becomes idle.
TypeScript
await client.callTool(
{ name: "entity_research", arguments: { user_query: "..." } },
undefined,
{
timeout: 60_000,
resetTimeoutOnProgress: true,
maxTotalTimeout: 1_800_000,
},
);
Python
from datetime import timedelta
result = await session.call_tool(
"entity_research",
{"user_query": "..."},
read_timeout_seconds=timedelta(minutes=10),
)
Recommended Settings
- Usage Timeout Reset on Progress
- Discovery 60 seconds Optional
- Research 10 minutes Yes
- Batch pipelines 30 minute cap Yes
If your MCP host manages the connection, update its tool timeout settings accordingly.
OAuth Session Lifetime
Carbon Arc MCP uses OAuth 2.0
Supported MCP clients, including Claude Desktop, Cursor, and the official MCP SDKs, automatically discover the OAuth endpoints, register dynamically, and complete browser-based authentication. No API keys are required.
No additional configuration is required to receive refresh tokens.
Token Lifetimes
| Credential | Lifetime | Behavior |
|---|---|---|
| Access Token | 7 days | Automatically refreshed without requiring another login |
| Refresh Token | 30 days | Rotates on every refresh. Requires browser sign-in after expiration. |
Refresh Token Rotation
Refresh tokens are single use.
Each refresh returns a new refresh token that must be stored by your client. Previous refresh tokens remain valid for roughly one minute to support concurrent requests, then expire.
Most MCP clients handle this automatically. Custom integrations must store the latest refresh token after every refresh.
What to Expect
Active users
As long as the connection refreshes at least once every 30 days, sessions remain active indefinitely.
Inactive users
If a connection sits idle for more than 30 days, you'll simply be asked to sign in again.
Subscription checks
Your Carbon Arc subscription is validated each time a refresh occurs.
If your subscription has expired or been suspended, refresh requests are rejected and the client prompts for re-authentication.
Long-running requests
Token expiration does not interrupt requests already in progress.
Authorization is checked when a tool starts. A research request can continue running even if the access token expires during execution.
Troubleshooting
| Issue | Likely Cause | Resolution |
|---|---|---|
| Research requests consistently fail after 60 seconds | Client timeout is too low | Increase the timeout or enable timeout reset on progress |
| Connection closes during a request | Client or proxy closed the connection | Verify streaming support and review proxy timeout settings |
| Only heartbeat messages appear | Request is still processing | This is expected for larger research jobs |
| Repeated timeouts | Query is too broad | Narrow the request or split it into smaller jobs |
| Authorization errors every hour | Client isn't refreshing tokens | Implement the refresh_token flow |
| Invalid refresh token after a successful refresh | Old refresh token was reused | Store and use the newly returned refresh token |
| Prompted to sign in again | Refresh token expired or subscription changed | Re-authorize through the browser and verify your subscription |
If you're unsure whether a failed request consumed tokens, contact support@carbonarc.co with the approximate request time.
Summary
- Discovery tools typically return in seconds.
- Research tools commonly take several minutes.
- Carbon Arc sends heartbeat events every 30 seconds during every tool call to keep requests alive.
- Most timeout issues come from MCP client settings, not the server.
- For research workflows, configure a 10-minute timeout and enable timeout reset on progress whenever possible.
- Access tokens automatically refresh every hour.
- Refresh tokens rotate on every refresh and remain valid for 30 days from the latest successful refresh.
- After 30 days of inactivity, sign in again to reconnect.