Skip to main content

Custom Integrations

Use this guide to connect Carbon Arc MCP to clients not covered by the Claude, ChatGPT, Codex, or Perplexity setup guides, including Cursor, internal agents, and custom MCP-compatible applications.

Carbon Arc exposes a remote MCP server over Streamable HTTP. Supported clients can discover OAuth endpoints, register dynamically, and complete browser-based authentication. Standard OAuth flows do not require API keys.

Prefer a guided setup?

If you're using Claude, ChatGPT, Codex, or Perplexity, start with the matching guide under Non-Native MCP.

Requirements

  • An MCP-compatible client that supports remote / Streamable HTTP servers
  • A Carbon Arc platform account with MCP access
  • The ability to complete a browser OAuth sign-in, or provide a Bearer token if supported by your client

Endpoints

ConnectorURLUse for
Core MCPhttps://mcp.carbonarc.aiDiscovery, search, and core insight / entity tools
Research MCPhttps://mcp.carbonarc.ai/researchEntity Research, Forecast, Acquire, Retain, Target, Upsell

Add both connectors if you need Research tools. See MCP Tools for the tools available through each endpoint.

Connect a custom client

Exact labels vary by client, but the setup follows the same pattern.

1. Add a remote MCP server

Add a new MCP or connector configuration and select Streamable HTTP, or the equivalent remote HTTP option.

2. Set the server URL

Start with the Core endpoint:

https://mcp.carbonarc.ai

Optionally add a second server for Research:

https://mcp.carbonarc.ai/research

3. Authenticate

OAuth (recommended)

Save the server and authenticate. Your client should open a browser window for Carbon Arc sign-in and manage tokens automatically.

Bearer token (if supported)

Paste your Carbon Arc API key as a Bearer token. You can find your key on your profile / API key page.

4. Verify tools

Confirm Carbon Arc tools appear in your client's tool list, then test the connection with a simple prompt:

What data do you have for Walmart?

Authentication notes for builders

If you're integrating Carbon Arc into a custom agent or SDK:

  • Prefer the standard MCP OAuth flow. Clients that correctly implement MCP OAuth can discover authorization endpoints and refresh tokens without additional configuration.
  • Access tokens expire after 1 hour. Your client should refresh them automatically in the background rather than assuming the initial token will remain valid.
  • Refresh tokens rotate after each refresh and are effectively single-use. Always store the latest refresh token returned to your client. Refresh tokens remain valid for 30 days from the last successful refresh, after which the user must sign in again.
  • Long-running Research calls are authorized when the tool starts. An access token expiring mid-request does not cancel work already in progress.

See MCP Timeouts & OAuth for full authentication details.

Timeouts and streaming

Research and larger analytical requests can take several minutes. Carbon Arc sends heartbeat events during tool calls to keep the connection alive.

WorkloadSuggested client timeout
Discovery / search~60 seconds
Research tools~10 minutes, resetting timeout on progress when supported

If requests consistently fail around 60 seconds, increase the client or proxy timeout before treating the failure as a server error.

See MCP Timeouts & OAuth for more detail.

Example client configurations

These examples are illustrative. Adapt field names to your client.

Streamable HTTP

{
  "name": "CarbonArcMCP",
  "type": "streamable-http",
  "url": "https://mcp.carbonarc.ai"
}

Research connector

{
  "name": "CarbonArcResearchMCP",
  "type": "streamable-http",
  "url": "https://mcp.carbonarc.ai/research"
}

Troubleshooting

IssueWhat to check
Tools never appearConfirm remote / Streamable HTTP MCP is enabled and the URL is correct
Auth loops every hourConfirm your client persists refreshed tokens and implements refresh_token correctly
Invalid refresh tokenConfirm your client stores the newly returned token after each rotation
Research fails around ~60sIncrease the tool timeout and enable timeout reset on progress
Connection drops mid-requestConfirm streaming support and check proxy idle timeouts

Still stuck? Contact support@carbonarc.co with the client name and approximate request time.