> ## Documentation Index
> Fetch the complete documentation index at: https://docs.colacloud.us/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Setup

> Connect Claude, Claude Desktop, Claude Code, and the Claude API to COLA Cloud.

## Choose a Claude Path

| Path                     | Authentication          | Best for                                                                 | Status                                                              |
| ------------------------ | ----------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------- |
| Claude custom connector  | OAuth                   | Claude.ai and Claude Desktop connector UI on supported paid Claude plans | Preferred connector path                                            |
| Claude Code or Agent SDK | API key in HTTP headers | Self-serve developer workflows and fallback setup                        | Supported                                                           |
| Claude API MCP connector | Bearer token parameter  | Server-side applications using Anthropic's Messages API MCP connector    | Supported when you provide a COLA Cloud API key as the bearer token |

## Claude Code with API Key

Create a COLA Cloud API key in **Dashboard > API Keys**, then add this to your
project `.mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "colacloud": {
      "type": "http",
      "url": "https://mcp.colacloud.us/mcp",
      "headers": {
        "Authorization": "Bearer ${COLA_API_KEY}"
      }
    }
  }
}
```

Then export your key before starting Claude Code:

```bash theme={null}
export COLA_API_KEY=cola_xxxx
```

Use prompts like:

* "Use COLA Cloud to find California wine approvals from the last 90 days."
* "Fetch details for `cola:24001001000001`."
* "Create a monthly saved search for new imported tequila approvals."

## Claude Custom Connector with OAuth

Claude's remote custom connector UI is the path for Claude.ai and current Claude
Desktop remote connectors on supported paid Claude plans. It uses OAuth rather
than a static COLA Cloud API key.

<Steps>
  <Step title="Open Connectors">
    In Claude, open **Customize > Connectors**. Team and Enterprise owners can add organization connectors from organization settings.
  </Step>

  <Step title="Add a custom connector">
    Choose a custom web connector and enter:

    ```text theme={null}
    https://mcp.colacloud.us/mcp
    ```
  </Step>

  <Step title="Authenticate">
    Complete the OAuth flow and grant the requested COLA Cloud scopes.
  </Step>

  <Step title="Enable per conversation">
    In a chat, use Claude's tools/connectors menu to enable the COLA Cloud connector for that conversation.
  </Step>
</Steps>

<Note>
  Claude Desktop remote connectors are configured through Claude's Connectors UI.
  Current Anthropic guidance says remote MCP servers are not connected by adding
  them directly to `claude_desktop_config.json`. The local Desktop JSON mechanism
  is for local MCP servers and desktop extensions.
</Note>

## Claude API MCP Connector

If you call Claude through the Anthropic API, pass the COLA Cloud MCP endpoint as
a remote MCP server and use your COLA Cloud API key as the bearer token for that
server.

```python theme={null}
import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-7",
    max_tokens=1000,
    messages=[
        {
            "role": "user",
            "content": "Use COLA Cloud to find recent Kentucky bourbon approvals.",
        }
    ],
    mcp_servers=[
        {
            "type": "url",
            "url": "https://mcp.colacloud.us/mcp",
            "name": "colacloud",
            "authorization_token": "cola_xxxx",
        }
    ],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "colacloud"}],
    betas=["mcp-client-2025-11-20"],
)
```

## Team and Enterprise Notes

* Owners may need to add the connector at the organization level before members can connect.
* Members still authenticate individually; the connector only receives data allowed by that user's COLA Cloud account.
* Review and disable write tools such as `create_scheduled_search` if your organization does not want assistants creating durable alerts.
* Research modes can invoke connector tools automatically. Disable write tools before using research workflows.

## Troubleshooting

| Symptom                                | What to check                                                                                    |
| -------------------------------------- | ------------------------------------------------------------------------------------------------ |
| Claude Code cannot connect             | Confirm `.mcp.json` uses `"type": "http"` and that `COLA_API_KEY` is exported in the same shell. |
| Claude custom connector asks for OAuth | Expected. The hosted Claude connector UI does not use static API-key headers.                    |
| OAuth connection fails after login     | The OAuth subject may not be linked to your COLA Cloud account yet.                              |
| Tools are not called                   | Explicitly say "Use COLA Cloud" and enable the connector for the conversation.                   |