Connect Cursor

Cursor reads MCP servers from an mcp.json file. Hawzu connects with an access token in a header.

---

Add the Server

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. Put the token in your environment rather than in the file. On macOS or Linux, add this to your shell profile:

   export HAWZU_TOKEN="your-token-here"

3. Open Cursor Settings → MCP → Add new MCP server, or edit ~/.cursor/mcp.json directly, and add:

   {
     "mcpServers": {
       "hawzu": {
         "url": "https://app.hawzu.com/mcp",
         "headers": {
           "Authorization": "Bearer ${env:HAWZU_TOKEN}"
         }
       }
     }
   }

4. Restart Cursor, then check that hawzu shows as connected in the MCP settings panel.

Do not commit the token

${env:HAWZU_TOKEN} keeps the credential out of the file. A token written into mcp.json inside a repository is a credential in your git history — and an MCP token reads every project in its workspace, so one committed to a repository hands a whole workspace’s records to whoever finds it.

---

Per-Project Configuration

A .cursor/mcp.json in a repository applies to that project only. Use the same shape as above, and keep using ${env:...} — a per-project file is more likely to be committed, not less.

---

What to Ask

Cursor’s agent will call the tools on its own once it knows the server is there:

• “Which Hawzu projects can you see?”
• “What test cases cover the checkout flow?”
• “Are there open defects linked to the tests for this module?”

---

If It Does Not Connect

Symptom	Cause
Server shows red or “failed”	The URL is wrong, or HAWZU_TOKEN is unset in the environment Cursor inherited. Restart Cursor after setting it.
${env:HAWZU_TOKEN} sent literally	Cursor did not resolve the variable — confirm the shell it launched from exports it.
Connects, but questions are refused	The workspace_id being asked about is not the one the token was issued for, or the token has been revoked. An MCP token has no role to check.
Cursor describes a tool differently from these pages	It is working from the tool list it fetched when it connected. Quit and reopen Cursor. See Keeping a connection current.