AI and agents

There are four ways to let software act for you in Sumhour: the assistant inside the app, AI apps connected over MCP, personal API tokens, and the sumhour command line tool. All four run the same operations as the web app, so your role, locked weeks and required notes apply to each. Their changes appear in Activity under your name, labelled with where they came from. Technical details are in the developer docs.

The assistant

The assistant is Pip, Sumhour’s small green helper. It sits in a bar at the bottom of every page: “Ask Pip to log time, check your week or draft an invoice”. Press ⌘J (Ctrl+J on Windows and Linux) or click the bar; on a phone it is a round button in the corner. The ⌘K palette also offers “Ask Sumhour” with your typed text. Ask in your own words: Pip can log and fix time, check your week, run reports and draft invoices, within your role. It also answers questions about Sumhour itself (“how do I import from Harvest?”) from this user guide, with a link to the page.

Each conversation starts with what Sumhour already knows about you: your projects, your hours this week and, by role, weeks waiting for approval and money still owed. Pip answers quick questions from that and looks up the details when it needs them.

Pip only helps with your work in Sumhour. Ask it to write an email, design something or answer a general question and it says so in one line.

It never changes anything without asking. Lookups run straight away and show as a small line. Anything that would change data stops and shows a card describing the change in words: the project and client, the date and duration, the invoice number. Nothing happens until you press the button, which names the change: “Create draft invoice”, or “Create 3 draft invoices” when there are several. Deletions show in red, for example “Delete entry”. “Cancel” tells Pip you declined, and typing a new message while a card is open counts as declining too.

It can be wrong, so read the card before you approve. “New chat” starts over. Each person can send 60 messages an hour and 200 a day.

Speaking to Pip

Where voice is on, the message box has a microphone button and a language button. Pip starts in your browser’s language when it can listen in it, otherwise English; the button lists your browser’s languages first and about 60 others below, and remembers your choice. Press the microphone, allow the browser to use it the first time, and speak. Your words appear as you talk; when you pause, Pip sends them. Press the square button to send early. With a card on screen, say “yes” or “no” (in English or Bangla, “হ্যাঁ” or “না”) to answer it, or press the button as usual. Your voice goes from the browser to Deepgram, which turns it into text; Sumhour keeps only the text.

Pip can also read its replies aloud. Press the speaker button at the top of the panel; it stays on in that browser until you press it again. Pip uses a voice for the language of the reply (Bangla, Hindi, Spanish, Japanese and about 30 others), stops as soon as you press the microphone or ask something new, and skips tables and code. Readings count towards a daily allowance; after that, replies stay on screen only until the next day.

The assistant needs an Anthropic API key on the server, and voice a Deepgram API key as well. On a self-hosted server without them, the bar, shortcut and palette entry, or the microphone, are not there.

Connect an AI app over MCP

AI apps that speak MCP connect to Sumhour at https://app.sumhour.com/mcp (a self-hosted server uses its own address). For Claude, follow Use Sumhour in Claude; the steps for other apps are in the MCP guide.

When you add the connection, the app sends you to Sumhour to sign in and approve it. The approval page is titled “Allow [app name] to use Sumhour?” and shows:

which address the request came from, or that the app registered itself so Sumhour cannot confirm its name
a “Workspace” picker, because one connection covers one workspace
the permissions it asks for, as checkboxes; untick anything you do not want to share

Press “Allow” or “Deny”. Only continue if you started the connection yourself. A request left open expires after ten minutes.

A connected app acts as you, never beyond your role, and only sees the tools you can use. Its changes are logged “via MCP” with the app’s name.

Every Sumhour tool that changes something is marked as a change, so Claude and other apps that honour that mark ask you before each one. API tokens and scripts make changes straight away. With the invoices permission an app can draft invoices and record payments, so grant it only to apps you trust. No app or token can send an invoice.

Connected apps are listed under “Connected apps” on the API tokens page (user menu, “API tokens”). “Disconnect” cuts access at once. Owners and admins see everyone’s connected apps there and can disconnect any of them.

Personal API tokens

A token lets a script, a Zapier step or an agent act as you in one workspace. Open the user menu, choose “API tokens” and press “New token”. Give it a “Name” that says where it will be used, so you can tell tokens apart. Set “Expires” to 30 days, 90 days, a year or never. For permissions, pick a preset or “Pick permissions”.

Preset	What it covers
Time tracking	Timer, entries, timesheets and the project list
Read only	Everything your role can see, nothing it can change
Everything your role allows	Full access within your role

“Pick permissions” offers thirteen, covering time, projects, expenses, invoices, reports, approvals and the team list, with a separate write permission where changes are possible. Two of them work only for owners and admins: adding clients and projects, and sending workspace events to apps such as Zapier, which subscribe a URL that then receives each event as it happens. Tokens made before a permission existed do not get it; make a new token to use it.

Press “Create token” and copy it; it is shown once. What a token can do is always the smaller of its permissions and your current role, checked on every call. If your role drops or you leave the workspace, the token shrinks or stops with it. Each token can make 120 requests a minute.

The list shows each token’s permissions, last use and expiry. “Revoke” stops a token at once. Owners and admins also see “Everyone else’s tokens” and can revoke them.

The sumhour command line tool

sumhour tracks time from a terminal: start and stop the timer, log finished time, list and edit entries, submit your week, add expenses and run reports. Every command takes --json, and commands that change data take --dry-run to show the request without sending it.

sumhour login
sumhour start acme portal -m "Kickoff"
sumhour stop
sumhour log 1:30 AH-2 -m "Design review"
sumhour week && sumhour submit

sumhour login shows a code such as WDJB-MJHT and opens /device in your browser. Check the code matches, pick the workspace and the permissions, and press “Approve”. If someone else sent you the link or code, deny it. The CLI then gets its own token, valid for 180 days, which shows under API tokens with a “CLI” tag. sumhour logout revokes it.

For scripts and CI, make a token in the app and set SUMHOUR_TOKEN instead of logging in. The npm package is published with the public launch. The CLI reference lists every command.

Turn these off for the whole workspace

Owners and admins control three switches under “Settings”, in “AI and API access”. All three are on by default.

Switch	When it is off
The assistant on every page	The bar and the shortcut disappear for everyone
AI apps over MCP (Claude, ChatGPT, Cursor)	Every connected app is refused, but none is disconnected
API tokens and the command line	Every personal token is refused, including ones used with AI apps, and no new tokens or CLI sign-ins can be made

Turning a switch off takes effect at once for everyone in the workspace. Existing tokens and connections are kept, so turning it back on restores them.