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

# Authentication

> OAuth 2.0 + PKCE authentication for the Venturu MCP server.

## Authentication is Optional

Most tools on the Venturu MCP server work **without authentication**. You can search businesses, browse brokers, and retrieve details without logging in.

Authentication is only required for tools that take action on behalf of a user:

| Tool                       | Auth Required |
| -------------------------- | ------------- |
| `search_businesses`        | No            |
| `search_brokers`           | No            |
| `get_business`             | No            |
| `get_broker`               | No            |
| `list_business_categories` | No            |
| `list_languages`           | No            |
| `contact_broker`           | **Yes**       |
| `contact_seller`           | **Yes**       |
| `who_am_i`                 | **Yes**       |

## How It Works

The Venturu MCP server implements the **OAuth 2.0 Authorization Code flow with PKCE** (Proof Key for Code Exchange), the standard for MCP authentication. Most MCP clients handle this flow automatically — you just approve the connection.

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Client as MCP Client
    participant Venturu as Venturu OAuth

    Client->>Venturu: 1. Register client (Dynamic Client Registration)
    Venturu-->>Client: client_id

    Client->>Venturu: 2. Authorization request + PKCE challenge
    Venturu-->>User: 3. Show consent screen
    User->>Venturu: 4. Approve access
    Venturu-->>Client: 5. Authorization code

    Client->>Venturu: 6. Exchange code + PKCE verifier for tokens
    Venturu-->>Client: 7. Access token + Refresh token

    Client->>Venturu: 8. API calls with Bearer token
```

### What Happens in Practice

1. **You trigger an authenticated tool** — e.g., ask the AI to contact a broker
2. **Your MCP client opens a browser window** to the Venturu consent screen
3. **You approve the connection** with your Venturu account
4. **The client receives tokens** and can make authenticated requests
5. **Tokens refresh automatically** — you won't need to log in again

## OAuth Endpoints

For client developers building MCP integrations, here are the standard discovery endpoints:

| Endpoint                          | URL                                                              |
| --------------------------------- | ---------------------------------------------------------------- |
| **Authorization Server Metadata** | `https://www.venturu.com/.well-known/oauth-authorization-server` |
| **Protected Resource Metadata**   | `https://www.venturu.com/.well-known/oauth-protected-resource`   |
| **Authorization**                 | `https://www.venturu.com/api/oauth/mcp/authorize`                |
| **Token**                         | `https://www.venturu.com/api/oauth/mcp/token`                    |
| **Dynamic Client Registration**   | `https://www.venturu.com/api/oauth/mcp/register`                 |

## Scopes

| Scope        | Description                                      |
| ------------ | ------------------------------------------------ |
| `mcp:access` | Access to all MCP tools, including contact tools |

## Token Lifetimes

| Token             | Lifetime                            |
| ----------------- | ----------------------------------- |
| **Access token**  | 1 hour                              |
| **Refresh token** | Managed automatically by the client |

Access tokens are encrypted JWE tokens. When an access token expires, compliant MCP clients will automatically use the refresh token to obtain a new one without requiring you to log in again.

## Dynamic Client Registration

The Venturu MCP server supports [RFC 7591 Dynamic Client Registration](https://tools.ietf.org/html/rfc7591). MCP clients can register themselves automatically without manual configuration. This means:

* No need to pre-register your application
* No client secrets to manage
* The client receives a `client_id` on first connection

<Info>
  If your MCP client supports the standard OAuth 2.0 discovery flow (via `.well-known/oauth-authorization-server`), authentication will work out of the box with no manual configuration.
</Info>

## Troubleshooting

<AccordionGroup>
  <Accordion title="I see 'This tool requires authentication'">
    You're calling a contact tool without being authenticated. Your MCP client should prompt you to log in — check for a browser popup or notification. If not, reconnect to the server and try again.
  </Accordion>

  <Accordion title="The OAuth window doesn't appear">
    Some MCP clients may not support OAuth flows yet. Check your client's MCP documentation for authentication support. You can still use all read-only tools without authentication.
  </Accordion>

  <Accordion title="My token expired">
    Access tokens last 1 hour. Your MCP client should automatically refresh them. If you're seeing auth errors after a long session, try disconnecting and reconnecting to the server.
  </Accordion>
</AccordionGroup>