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

# Connection Guide

> Connect AI agents to the Bizzy MCP server

This guide covers how to connect AI agents to the Bizzy MCP server, including
the available transports and troubleshooting common issues.

## Connection URL

Point your client at the Streamable HTTP endpoint:

```
https://mcp.bizzyco.ai/mcp
```

Configure this full URL — including the `/mcp` path — rather than the bare
domain. OAuth discovery lives at the domain root, so a client pointed at
`https://mcp.bizzyco.ai` completes sign-in but then fails on its first request.
The server now redirects MCP requests from the root to `/mcp` automatically, but
configuring the endpoint directly is the most reliable.

## Authentication

Modern MCP clients (Claude Desktop, Claude Code, Cursor, Windsurf) handle OAuth
2.1 + PKCE automatically — point them at the connection URL above and they walk
you through sign-in and consent. See
[Authentication](/mcp-server/authentication) for the full flow.

## Transports

The MCP server supports two transports:

* **Streamable HTTP** — `https://mcp.bizzyco.ai/mcp`. The current MCP transport;
  recommended for new clients.
* **Server-Sent Events (SSE)** — `https://mcp.bizzyco.ai/sse`. Kept for
  compatibility with clients that implement the earlier SSE transport.

Pick whichever your client supports; you do not need to configure both.

## Health Check

Verify the MCP server is available before connecting:

```bash theme={null}
curl https://mcp.bizzyco.ai/health
```

Response:

```json theme={null}
{ "status": "ok" }
```

<Note>
  The health check endpoint doesn't require authentication. Use it to verify
  connectivity before attempting to establish an authenticated connection.
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection refused or timeout">
    **Possible causes:**

    * Network connectivity issues
    * Firewall blocking outbound HTTPS
    * Incorrect URL

    **Solutions:**

    1. Verify network connectivity: `curl https://mcp.bizzyco.ai/health`
    2. Check firewall rules allow outbound HTTPS (port 443)
    3. Ensure you're using `https://` not `http://`
  </Accordion>

  <Accordion title="Sign-in succeeds but the connection then fails">
    If the browser consent flow completes but your client reports a failure (often `HTTP 405`) on its first request, the client is almost certainly pointed at the domain root instead of the transport endpoint. OAuth discovery lives at the root, so sign-in succeeds and only the first transport request reveals the wrong path.

    **Solution:** set your connection URL to the explicit endpoint — `https://mcp.bizzyco.ai/mcp` (or `https://mcp.bizzyco.ai/sse`). The server redirects MCP requests from the root to `/mcp` automatically, but configuring the endpoint directly is the most reliable.
  </Accordion>

  <Accordion title="401 Unauthorized">
    A 401 is the canonical signal that your client needs to run (or re-run) the OAuth flow. The `WWW-Authenticate` header on the response points to a route-scoped protected-resource metadata URL (e.g. `/.well-known/oauth-protected-resource/mcp`), which a spec-compliant client uses to start discovery.

    **Solutions:**

    1. Confirm your client supports OAuth 2.1 + PKCE + Dynamic Client Registration. Most current MCP clients do.
    2. Make sure you completed the consent screen in your browser. If you cancelled it, retry the connection from your client.
    3. If the client looks stuck after a successful consent, remove and re-add the Bizzy server in the client so it re-registers via DCR.
    4. See [Authentication](/mcp-server/authentication) for the full handshake.
  </Accordion>

  <Accordion title="403 Forbidden">
    **Possible causes:**

    * Insufficient permissions for the requested tool
    * The tool's category wasn't granted during consent
    * Account suspended

    **Solutions:**

    1. Check the error message for details
    2. Re-run the consent screen from your client and grant the tool categories you need
    3. Check your agent's permissions in the dashboard
  </Accordion>

  <Accordion title="Rate limited">
    Throttling shows up in two different shapes — check the response body, not just the status code.

    **A tool call returns a JSON-RPC error with `code: -32004`.** You've spent your plan's per-minute MCP allowance (Free 10, Starter 30, Professional 100, Enterprise 300). The HTTP response is otherwise normal, so a client that only inspects status codes will miss this.

    **The request returns HTTP `429`.** You've hit the per-(user, client) transport backstop of 600 requests per 60 seconds — well above any plan's tool-call limit, so this usually means a runaway retry loop.

    **Solutions:**

    1. Wait `data.retryAfter` seconds (JSON-RPC error) or the `Retry-After` header (HTTP 429) before retrying
    2. Implement request queuing or throttling, with exponential backoff as a fallback
    3. See [Rate limits](/mcp-server/authentication#rate-limits) for the full breakdown
  </Accordion>

  <Accordion title="SSE connection drops">
    **Possible causes:**

    * Network instability
    * Idle timeout
    * Server maintenance

    **Solutions:**

    1. Implement automatic reconnection logic
    2. Send periodic ping messages to keep the connection alive
    3. Check [status.bizzyco.ai](https://status.bizzyco.ai) for service issues
  </Accordion>
</AccordionGroup>

## Session Management

MCP connections are stateful. Each connection receives a unique session ID that
persists for the duration of the connection.

* **Session IDs** are generated automatically on connection
* **Sessions expire** after extended idle periods
* **Reconnections** create new sessions - previous session state is not
  preserved

<Note>
  Design your agent to be stateless where possible. Don't rely on server-side
  session state persisting between tool calls.
</Note>

## Next Steps

<CardGroup cols={2}>
  <Card title="Available Tools" icon="wrench" href="/mcp-server/tools">
    Explore the complete list of MCP tools
  </Card>

  <Card title="Integrations" icon="puzzle-piece" href="/mcp-server/integrations">
    See examples of MCP integrations
  </Card>
</CardGroup>