🐕 Houndly MCP Server

Model Context Protocol server for the Houndly test management platform

Connect Claude Code, Claude Desktop, Cursor or any MCP-compatible assistant to your Houndly workspace: list projects, write test cases, open bugs and create runs by asking for them.

📦 Installation

Nothing to clone or build — the server runs from npm.

Claude Code

claude mcp add houndly \
  --env HOUNDLY_API_URL=https://your-workspace.moraylab.ai \
  --env HOUNDLY_API_KEY=hnd_your_api_key \
  -- npx -y @houndly/mcp-server

The address is the one you log in through. It names your workspace, so there is nothing else to configure.

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows:

{
  "mcpServers": {
    "houndly": {
      "command": "npx",
      "args": ["-y", "@houndly/mcp-server"],
      "env": {
        "HOUNDLY_API_URL": "https://your-workspace.moraylab.ai",
        "HOUNDLY_API_KEY": "hnd_your_api_key"
      }
    }
  }
}

Cursor

The same object, in .cursor/mcp.json.

Restart the client afterwards — MCP servers are read at startup, so an open session keeps the old settings.

⚙️ The two values

| Variable | What it is | Where to find it | |---|---|---| | HOUNDLY_API_URL | Your workspace address | The one in your browser bar when you use Houndly | | HOUNDLY_API_KEY | API key, starts with hnd_ | Houndly → Integrations |

The workspace is read from the address — https://acme.moraylab.ai is workspace acme — so there is no second value to keep in sync.

HOUNDLY_SUBDOMAIN still exists for the case where the address cannot name a workspace: pointing straight at a backend host, or at localhost in development. Set it there, and it wins over whatever the address implies.

🔐 Authentication

The server authenticates with a personal Houndly API key — one that belongs to you, not to the workspace:

• It acts with your own role. A VIEWER's key can only read.
• Revoking it stops that key and nothing else. Nobody else's reporters or MCP clients are affected.
• It is shown once, when you create it. Lost it? Revoke and make another.

Create one in Houndly → Integrations → Personal API keys.

🛠️ Available tools

| Area | Tools | |---|---| | Projects | list_projects, get_project, create_project, update_project, delete_project | | Suites | list_test_suites, get_test_suite, create_test_suite, update_test_suite, delete_test_suite | | Cases | list_test_cases, get_test_case, create_test_case, update_test_case, delete_test_case | | Runs | list_test_runs, get_test_run, create_test_run, update_test_run, delete_test_run | | Bugs | list_bugs, get_bug, create_bug, update_bug, delete_bug | | Executing | record_test_run_result, add_test_run_result_attachment, upload_test_evidence, set_test_run_case_notes |

▶️ Recording what a run found

record_test_run_result writes the outcome of one case inside a run — the thing that used to exist only in the UI. It appends: earlier executions stay in the history, the latest one is what counts, and the run's stats come back with the reply so you can watch them move.

record_test_run_result          testRunId, testCaseId, result, comment, durationMs, attachments
upload_test_evidence            filePath → { url, fileName, fileSize, type }
add_test_run_result_attachment  resultId, attachments   — evidence that arrived late
set_test_run_case_notes         testRunId, testCaseId, notes — independent of any execution

Two things worth knowing:

• The executor is the owner of the API key. There is no field for claiming someone else ran it, which is what makes the history worth reading.
• A run has to be started. Recording against a PENDING run is refused by the API; start the run first.

💡 Ask for it in words

List all my Houndly projects
Create a project called "E-Commerce" with key "ECOM"
In project TP, write a test case for logging in with valid credentials
Show me every open bug in project XYZ
Create a run for project ABC covering the smoke suites

🐛 Troubleshooting

| Symptom | Cause | |---|---| | HOUNDLY_API_KEY environment variable is required | The key is missing from the client config — the env block is per server, not global | | 401 Unauthorized | Wrong key, or it was regenerated in Houndly since you copied it | | 403 Forbidden | The key is valid but the operation is not allowed for this workspace | | "Workspace not found" / empty results | The address names a different workspace than the key belongs to | | Cannot connect | Check the address — it should be exactly what you log in through, scheme included |

Claude Desktop logs its MCP servers to ~/Library/Logs/Claude/mcp*.log. In Claude Code, claude mcp list shows whether the server started.

🔧 Local development

From a checkout of the monorepo:

pnpm install
pnpm --filter @houndly/mcp-server run build   # or run watch

Point the client at node /absolute/path/to/packages/mcp-server/build/index.js instead of npx. Locally there is no workspace in the address, so set both HOUNDLY_API_URL=http://localhost:3001 and HOUNDLY_SUBDOMAIN.

Tests: pnpm --filter @houndly/mcp-server run test.

📚 Resources

• MCP specification
• Houndly documentation

📄 License

MIT

Built with ❤️ by the Houndly Team