Connect ChatGPT

There are two ways in, and they authenticate differently. The ChatGPT app signs you in; the OpenAI API takes a token.

---

ChatGPT Custom Connector

1. In ChatGPT, enable developer mode under Settings → Connectors → Advanced. Custom connectors are available on Plus, Pro, Business, Enterprise and Education plans.

2. Choose Create and enter the server URL:

   https://app.hawzu.com/mcp

3. Choose OAuth as the authentication method and confirm.

4. On the Hawzu consent screen, check the address the access will be sent to, choose which workspace the connection is for, then choose Allow read access.

5. Enable the connector in a conversation and ask it something about your projects.

Check the address, not the name

Any application can call itself anything during setup. The Hawzu consent screen shows the address your access will actually be sent to. If you do not recognise it, do not continue.

---

OpenAI Responses API

The API takes the token directly, so no browser step is involved.

1. Create an access token in Hawzu, setting Used for to MCP (AI clients). See Create an access token.

   An existing API token will not work here — MCP and the REST API take separate tokens.

2. Pass the server as an mcp tool:

   from openai import OpenAI
   
   client = OpenAI()
   
   response = client.responses.create(
       model="gpt-5",
       tools=[{
           "type": "mcp",
           "server_label": "hawzu",
           "server_description": "Read-only access to Hawzu test management records.",
           "server_url": "https://app.hawzu.com/mcp",
           "authorization": "YOUR_TOKEN",
           "require_approval": "never",
       }],
       input="Which Hawzu projects can you see?",
   )

3. The authorization value is not stored by the API — send it on every request.

Every tool is a read

require_approval: "never" is safe here in a way it would not be for a general connector: the Hawzu MCP server exposes no tool that can change anything. The worst outcome of an unapproved call is a query you did not want.

---

If It Does Not Connect

Symptom	Cause
Connector will not save	The URL must be exactly https://app.hawzu.com/mcp. ChatGPT also requires a public HTTPS address — it cannot reach a private network.
401 from the API	The token is wrong, expired, or revoked.
Connects, but questions are refused	On a connector, your own role cannot read that data — it acts as you. On an API token, the workspace_id is not the one the token was issued for, or it has been revoked.
ChatGPT describes a tool differently from these pages	It is working from the tool list it fetched when it connected. Toggle the connector off and on. See Keeping a connection current.

---

Disconnecting

A connector is removed in ChatGPT’s settings, and the underlying grant is revoked in Hawzu under Settings → Security → Connected apps.

An API token is revoked from the Access Tokens page, which cuts off everything using it.