MCP server · HumanHours docs

HumanHours runs a hosted Model Context Protocol server, so any MCP client can log agent ROI and ask about a workspace in plain language. There is nothing to install and no API key to paste: you connect once over OAuth, sign in with your HumanHours account, and pick the workspace the assistant may act on.

Endpoint

https://mcp.humanhours.dev/mcp

The transport is streamable HTTP. Authentication is OAuth 2.1 (PKCE), so the connect flow opens your browser, you log in to HumanHours, approve the connection, and the client receives an org-scoped token. No hh_live_ key changes hands.

Connect a client

Claude Desktop / claude.ai

Open Settings → Connectors → Add custom connector.
Paste the URL https://mcp.humanhours.dev/mcp.
Click through the HumanHours login, choose your workspace, and click Allow.

The HumanHours tools appear in the connector list. You can now ask things like "how much money did my support-classifier save this month?" or "enrich acme.com into a labour-cost business case".

Cursor, Claude Code, and other MCP clients

Point any client that speaks streamable HTTP at the same URL. For example, in a client that uses a JSON config:

{
  "mcpServers": {
    "humanhours": {
      "type": "http",
      "url": "https://mcp.humanhours.dev/mcp"
    }
  }
}

The first call triggers the OAuth flow in your browser.

Permissions and control

When you connect, you choose a workspace and grant a set of scopes:

Scope	What it allows
`track:write`	Log agent task events.
`read:reports`	Read summaries, reports, agents, task types, and the company library.
`enrich:write`	Enrich company domains (consumes lookup credits).

Only a workspace owner or admin can connect an application. Every connection is listed under Connected apps in the dashboard, where you can revoke it at any time; revoking stops access immediately.

Plan limits and quotas apply exactly as they do over the API: the report tools need a Pro plan, enrichment draws on your monthly lookups, and event tracking counts toward your plan's volume.

Tools

Each tool maps onto the same logic as the REST API, so the numbers match your dashboard to the cent.

Logging

Tool	Does
`track_event`	Record one agent task event and compute the hours and money it saved. Pass `model` + token counts to auto-derive the run's cost for true net ROI.

Reading

Tool	Does
`get_summary`	Aggregated ROI for a period, with a daily trend.
`time_saved_report`	Hours saved, grouped by agent, task type, model, client, or time.
`cost_saved_report`	Money saved, grouped the same ways.
`leaderboard`	Top agents by a chosen metric.
`get_usage`	Event usage against the plan's included quota.
`list_agents`	Agents tracked, with 30-day hours and money saved.
`list_task_types`	Built-in plus custom task types.

Enrichment

Tool	Does
`enrich_company`	Turn a domain into roles, per-hour wages, and an annual labour-cost case.
`get_company`	Read one enriched company from the library.
`list_companies`	List the workspace's company library, optionally by tag.
`bulk_enrich`	Queue a background job for many domains; returns a job id.
`get_job`	Check the status of a bulk enrichment job.

Errors

Tools surface the same error envelope as the API. A free workspace that runs out of lookups gets a clear lookup_quota_exceeded; a plan without the reports feature gets feature_locked. See Errors for the full list.