---
name: combined-agent-setup
description: Set up or troubleshoot a Combined remote MCP connection for the user's chosen AI client, preserving the account scope, OAuth flow, and existing source grants. Use when adding Combined to an agent or fixing connection discovery.
---

# Connect an agent to Combined

Help the user connect their chosen agent to the Combined account they intend to use. Prefer the current client-specific configuration generated by Combined's Set up or Access workspace. This skill supplies connection procedure; it does not grant access to the user's data.

## Establish the connection path

Combined's public remote MCP endpoint is:

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

Replace `ACCOUNT_UUID` with the account the user selected. It fixes tenant scope and is not an authentication secret. Do not infer an account from unrelated browser sessions or choose another account to bypass a failure.

The service uses Streamable HTTP. For a client supporting OAuth, configure the account-specific URL and begin connection from that client. A `401` challenge during discovery can be expected: `WWW-Authenticate` advertises the resource metadata used to find the authorization server. Let the user complete sign-in and review the requested grant.

For unattended runtimes, use the separately provisioned agent credential as a secret environment variable. The client must support the actual header and environment-expansion syntax used. Do not paste provider API keys or a Combined bearer token into prompts, public config, URLs, or committed files.

## Configure only the selected client

Read the current documentation for that client or use its generated Combined configuration. Client config formats differ; do not call a generic object valid for every agent.

The documented Claude Code project configuration has this shape:

```json
{
  "mcpServers": {
    "combined-context": {
      "type": "http",
      "url": "${COMBINED_API_URL}/mcp?account_id=${COMBINED_ACCOUNT_ID}",
      "headers": {
        "Authorization": "Bearer ${COMBINED_TOKEN}"
      }
    }
  }
}
```

This example assumes the documented runtime variables are supplied securely. Prefer OAuth when the selected workflow supports it. In Claude Code, `claude mcp list` can check the registered connection. For another client, use that client's actual connection UI or documented command instead of inventing a corresponding command.

Preserve unrelated MCP entries when editing a configuration. Configuring a connection does not authorize installing additional tools, broadening grants, sending source-authorization emails, or making provider writes.

## Verify the result

Refresh the client tool list. Combined exposes `list_sources`, `list_datasets`, `describe_dataset`, `get_freshness`, `search_context`, and `query_sql` as read-only tools; client prefixes may vary.

Call `list_sources` and confirm that the expected account's granted sources are visible. If a first query is requested, describe a relevant granted dataset and run a small bounded read. Source authorization and ingestion must have produced committed data before that data can be queried.

Distinguish these states in the result: configuration saved, authentication completed, tools discovered, intended source visible, and requested query completed. Do not describe a saved config alone as a successful data connection.

If connection fails, check URL/account scope, transport, OAuth challenge handling, and environment expansion. If access is denied, surface the missing grant. Preserve a correlation ID when present, without including credentials in diagnostics. After a specific correction, retry once; do not loop through identical denied requests or weaken access policy.

## References

- [Combined](https://www.trycombined.com/)
- [MCP connection and tools](https://www.trycombined.com/docs/integrations/mcp)
- [First agent connection](https://www.trycombined.com/docs/getting-started/quickstart)
- [Connection troubleshooting](https://www.trycombined.com/docs/troubleshooting/query-and-mcp)
- [Claude Code tutorial](https://www.trycombined.com/resources/connect-claude-code-to-business-data)