Security
How the Hoursmith MCP server handles your token and permissions over stdio or HTTP — it adds nothing beyond the REST API, never stores 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
- For stdio clients, the token lives only in your client's config (for example,
claude_desktop_config.json). - For HTTP clients, the token is sent as a request header such as
Authorization,x-api-key, orapi-key. - 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 or HTTP client custom headers hold a live credential. Protect them like any other secret: don't commit them to version control, and don't paste their contents into screenshots or support tickets.
HTTP mode binds to 127.0.0.1 by default. Only set HOURSMITH_MCP_HOST=0.0.0.0 if you intentionally
want other machines to reach the endpoint, and only on a network you trust.
Destructive tools
Five tools can remove or archive data: delete_client, archive_project, archive_task,
delete_time_entry, and delete_expense. Each one requires an explicit confirm: true
argument — the server rejects the call without it, so an assistant can't delete data on a stray
instruction. The same API guards still apply (e.g. delete_client refuses if the client has active
projects or invoices, and delete_time_entry fails on already-invoiced entries), and every tool
exposes read-only/destructive hints so capable clients can warn you first.
Still, 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 a stdio client's config, or replace the custom token header in an
HTTP client, then restart or reconnect 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 tokens or HTTP headers, 402 plan errors, old Node, wrong config paths, and stale client reloads.