Fix MCP authentication errors when connecting business data

Diagnose MCP 401, 403, missing tools and empty datasets in Cursor or Claude. Follow the connection stages and download a reusable diagnostic worksheet.

By the Combined team · September 14, 2026

For business-data analysis, Combined gives your agent one scoped MCP connection to synced sources. If the connection fails, identify the first failing stage: endpoint, authentication, data grant or query. An initial 401 can be an OAuth discovery challenge; a connected server with no permitted data needs a different fix. Follow the steps below to get from a visible server to a verified business-data query.

Start with the first failing stage

Combined MCP symptoms and next checks
Symptom	Likely stage	Next check
Timeout, DNS failure or no server entry	Client configuration or reachability	Correct JSON file, enabled server, URL and network path
401 before sign-in	OAuth discovery or missing credential	Read the authentication challenge and follow the configured sign-in route
401 after sign-in or after previously working	Credential validation	Expired/revoked credential, token audience, refresh and the exact endpoint
403, or an expected source is not visible	Account or source authorization	Current identity, account boundary and the specific data grant
422 from a SQL operation	Query validation	One bounded read-only query using discovered names
Successful query, incomplete answer	Data or result coverage	Freshness, selected fields, mapping and truncation

These meanings describe Combined's documented responses. An edge proxy can generate its own error before Combined handles the request; preserve the time and correlation ID to locate the failing layer. Download the connection diagnostic worksheet to record the checks without copying credentials or customer data.

1. Check the endpoint and transport

Combined's business-data MCP endpoint uses Streamable HTTP:

https://platform.trycombined.com/mcp?account_id=ACCOUNT_UUID

Use the account ID supplied by Combined's Access workspace. The marketing homepage and the documentation URL are not MCP endpoints. Keep the account parameter in the private client configuration; it selects the data boundary and does not authenticate the caller.

Check the URL your client actually requests. A redirect to another hostname can interfere with authentication; configure the intended endpoint directly instead of forwarding a credential through an unrelated origin. Claude's connector troubleshooting documents this failure mode.

In Cursor, start from the downloadable configuration. In Claude Code, use the HTTP setup command.

2. Distinguish the first 401 from a failed login

Before login, Combined returns a WWW-Authenticate challenge with a pointer to protected-resource metadata. The client follows that discovery chain to the authorization server. A first 401 is therefore compatible with a working OAuth flow. Repeatedly retrying that unauthenticated request will not complete it.

This public request checks the metadata path without sending a token or querying business data:

curl --silent --show-error --max-time 20 \
  'https://platform.trycombined.com/.well-known/oauth-protected-resource/mcp'

A valid response establishes metadata reachability only. Your client still needs to authenticate and receive access to the relevant account and sources. Follow the authorization server advertised by the metadata; do not guess an authorization URL on the marketing domain.

After a previously working login fails, check whether the credential or grant expired or was revoked. Complete the supported sign-in or replacement flow. An API key for HubSpot or Stripe is a source credential, not a Combined agent credential, and must not be pasted into the Combined MCP bearer header.

For provisioned credentials, confirm that the running client expands its environment variables. A literal placeholder sent as the bearer value cannot authenticate. Keep the live token in the runtime's secret setup and use the client-specific interpolation syntax.

3. Resolve connected-but-empty or denied access

Authentication identifies the caller. Grants determine which business data that caller can query. Seeing the six Combined tools does not mean every source is available, and a human's administrative role does not automatically supply the agent's data permissions.

Confirm the intended account ID and the identity used by the client.
In Access, inspect the grant for the precise sources and datasets the question needs.
Confirm the source authorization is complete and its selected data has synced.
Refresh the client connection and call list_sources again.
Use list_datasets and describe_dataset on an available source.

Combined can return 404 for an invisible resource as well as a missing one. Check discovery and scope before treating that status as proof the dataset does not exist. Request the narrow grant needed for the task rather than broad account access.

4. Verify the query, then return to the business question

Once discovery works, run a small read-only query using the exact relation and field names returned by Combined. Bind values with parameters. A 422 calls for checking the query and its limits; a 429 calls for respecting rate or resource bounds. Reauthentication does not correct a misspelled field or an oversized query.

Inspect the receipt, freshness and truncation information. Ask for an aggregate when the question needs a total. Do not sum a truncated row sample and present it as the whole account. If the query crosses HubSpot and Stripe, check customer mapping and aggregate both sources before joining.

The join lab reproduces duplicate totals, and the answer-verification lab lets you inspect deliberately constructed evidence failures. Both work with public teaching data, so you can understand the failure before retrying a production question.

If the issue persists, retain the client version, UTC timestamp, failing tool and correlation ID in your diagnostic worksheet. Remove tokens, cookies, account query values and business records before sharing it. The MCP reference troubleshooting covers the remaining query and coverage limits.

Sources and further reading

Explore the documentation behind this guide. Product details checked on September 14, 2026.