Security
How the Hoursmith MCP server handles your token and permissions — it adds nothing beyond the REST API, never stores or prints your token, and uses HTTPS.
The MCP server is deliberately boring on security: it adds nothing beyond the REST API. Every tool runs as the membership that minted your token, your token stays on your machine, and all traffic is HTTPS.
Permissions follow your token
The server grants no powers of its own. Each tool runs with the exact permissions of the membership whose token you configured:
- An Owner or Admin token reaches the whole workspace.
- A Manager Manager token can read everything and write clients, projects, tasks, and time.
- A Member Member token is limited to their own time and the projects they're on — and Members can't touch invoices, expenses, or clients.
Mint the token from a membership that has exactly the access you want your assistant to have. To give a teammate's AI narrower reach, give them a token created under a lower role. See Permissions & plans and Roles explained.
The same plan rule applies as everywhere else: the token's workspace must be on Studio Studio or Agency Agency, or every call returns a 402 plan error.
How your token is handled
- The token lives only in your client's config (for example,
claude_desktop_config.json). - The server never stores your token.
- It never prints your token to stdout — the server logs only to stderr.
- All traffic to Hoursmith is over HTTPS.
Your config file holds a live credential in plain text. Protect it like any other secret: don't commit it to version control, and don't paste its contents into screenshots or support tickets.
Destructive tools
Five tools can remove or archive data: delete_client, archive_project, archive_task,
delete_time_entry, and delete_expense. The server applies the same guards as the API — for
example, delete_client refuses if the client has active projects or invoices, and
delete_time_entry fails on already-invoiced entries — but it won't second-guess a valid request.
Review what your assistant proposes before approving it. See
Available tools.
Rotating your token
To rotate the token — for instance, if it may have leaked:
Revoke the old token
Go to Settings → API and revoke the current token. It stops working immediately.
Mint a new one
Create a replacement token and copy it — it's shown only once.
Update your config
Replace HOURSMITH_API_TOKEN in your MCP client's config with the new token, then restart the client.
Example prompts
Real things you can ask your AI assistant once Hoursmith MCP is connected — log time, look up unpaid invoices, create a client, and more.
Troubleshooting
Fix common Hoursmith MCP problems — missing or wrong token, 402 plan errors, old Node, the wrong config path, and forgetting to restart.