cob-portal-mcp
Officialby callobuzz
README.md
# cob-portal-mcp
> [!TIP]
> **[Open the cob-portal-mcp guide page →](https://callobuzz.github.io/cob-portal-mcp)**
> Install, the safety model, every tool, the key scopes and the FAQ, on one page.
**[npm](https://www.npmjs.com/package/cob-portal-mcp)** · **[Releases](https://github.com/callobuzz/cob-portal-mcp/releases)** · **[Changelog](./CHANGELOG.md)** · **[Callobuzz open source](https://callobuzz.com/open-source)**
[](https://github.com/callobuzz/cob-portal-mcp/actions)
[](https://github.com/callobuzz/cob-portal-mcp/releases)
[](https://www.npmjs.com/package/cob-portal-mcp)
[](./LICENSE)
[](https://nodejs.org/)
[](https://www.typescriptlang.org/)
[](https://github.com/callobuzz/cob-portal-mcp)
**An MCP server for the Call O Buzz portal.** It lets an AI agent (Claude Code, Claude Desktop, or any MCP client) read
tasks and send **drafts** and **notes** to the portal. It runs on your computer and talks to the portal API with a personal
API key.
> [!IMPORTANT]
> **The agent can only make drafts and notes.** It cannot assign work, approve a draft, change a task, pay, send mail or
> delete anything. A person must approve every draft in the portal before it becomes a task, and that person decides who
> gets it. Every note it writes is marked as written through the key.
## Why
A good agent can plan work, write a test plan or break a goal into tasks. The portal is where a team tracks that work. This
server connects the two, and keeps a person in charge:
- **The agent reads.** It lists tasks, templates and categories, and reads one task with its steps, answers and notes.
- **The agent proposes.** It sends draft tasks (a main task with sub-tasks) or a test plan as a check list draft.
- **A person decides.** The drafts wait in the portal. A person approves, rejects and assigns them.
- **The key sets the reach.** The server offers only the tools that the scopes of the key allow.
## Prerequisites
- **Node.js 22 or newer.**
- **A portal account** with two-step sign-in (2FA) on.
- **A personal API key** from the portal (see [Make a key](#make-a-key)).
## Install in one command
1. Make a key (see [Make a key](#make-a-key)). Copy it.
2. Add the server to your AI agent. npx downloads it from npm and starts it. Nothing is built on your computer.
### Claude Code
```bash
claude mcp add cob-portal \
--env COB_PORTAL_URL=https://your-portal-address \
--env COB_PORTAL_KEY=cob_your_key_here \
-- npx -y cob-portal-mcp
```
### Claude Desktop
Add this to `claude_desktop_config.json`, then restart Claude Desktop:
```json
{
"mcpServers": {
"cob-portal": {
"command": "npx",
"args": ["-y", "cob-portal-mcp"],
"env": {
"COB_PORTAL_URL": "https://your-portal-address",
"COB_PORTAL_KEY": "cob_your_key_here"
}
}
}
}
```
The portal's Profile page shows this block with your new key and the portal address filled in ("Copy MCP setup").
3. Check it: ask the agent to run `whoami`. It answers with your name, the key name and its scopes.
Notes:
- To stay on one version, add it: `cob-portal-mcp@0.9.0`.
- To run it straight from GitHub instead of npm, use `github:callobuzz/cob-portal-mcp` (or `#v0.9.0` for one version).
- To use a folder copy, clone the repository and write `node <path>/dist/cli.js` in place of `npx -y ...`. On Windows write
the path with forward slashes, for example `J:/callobuzz/mcp-servers/cob-portal-mcp/dist/cli.js`.
Why it works with no build: the built files in `dist/` are in the npm package and committed to the repository, and `bin`
points at `dist/cli.js`. npx installs the two runtime packages (`@modelcontextprotocol/sdk`, `zod`) and runs it. There is no
`prepare` script, so an install never needs the build tools.
## Settings
| Variable | Needed | Meaning |
| ----------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `COB_PORTAL_URL` | yes | The portal address, as the Profile page shows it. It must be https; plain http is allowed only for `localhost`. |
| `COB_PORTAL_KEY` | yes | A personal key that starts with `cob_`. The server sends it only as an `Authorization: Bearer` header. It never writes it to a log, an error or a URL. |
| `COB_PORTAL_TIMEOUT_MS` | no | How long to wait for one portal answer. Default `30000`. Minimum `1000`. |
## Make a key
1. Sign in to the portal. Your account needs two-step sign-in (2FA) on.
2. Open **Profile**, then **API keys**.
3. Make a new key. Choose its scopes and how long it lasts. Copy it at once. The portal shows it only one time.
4. Put it in `COB_PORTAL_KEY`. A key acts as you, cut down to its scopes. It never has more rights than you.
If a key stops working, make a new one on the same page.
## Scopes
| Scope | What it allows |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `work:read` | Read tasks, task templates and task categories. |
| `work:draft` | Send draft tasks and check lists for approval. Read your draft batches. |
| `work:comment` | Write notes on tasks. |
| `checks:read` | Read check list results. |
| `changes:read` | Read the current portal set-up (settings, job roles, people and their roles, and more). Changes nothing. |
| `changes:draft` | Draft change sets for a person to approve. Read, withdraw and list your own sets. Never approves, applies or undoes. |
| `records:read` | Read people's records: work time, hiring, leave, attendance, roster, presence, tests, targets, letters, documents and pay (pay for the admin key only). Changes nothing. |
At start the server calls `GET /api/v1/me` and offers **only the tools whose scope the key has**. `whoami` needs no scope.
## Tools
| Tool | Scope | What it does |
| ------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------- |
| `whoami` | none | Shows the person, the key name, its scopes and its end date. |
| `list_tasks` | `work:read` | Lists tasks (`scope` mine or team, `status`, `limit`, `cursor`, `category`, `parent_id`, `assignee`, `title`). |
| `get_task` | `work:read` | Reads one task with its steps, answers, notes, category, parent and sub-task count. |
| `list_templates` | `work:read` | Lists the published task templates, with their category. |
| `list_categories` | `work:read` | Lists the task categories the portal offers. |
| `get_check_results` | `checks:read` | Reads the test runs and skips of a check list task. File names only. |
| `add_comment` | `work:comment` | Writes a note on a task. |
| `draft_tasks` | `work:draft` | Sends a batch of draft tasks. A batch can hold main tasks with their sub-tasks (see below). |
| `draft_checklist` | `work:draft` | Sends a test plan (plan JSON) as one draft with a check list. |
| `list_drafts` | `work:draft` | Lists the draft batches you sent. |
| `get_draft` | `work:draft` | Reads one draft batch, with the state, category and parent of each draft. |
| `list_change_areas` | `changes:read` | Lists the areas you may draft for, the kinds of change and the shape of each value. Call it first. |
| `read_settings` | `changes:read` | Reads settings (`group`, `search`, `changed_only`). |
| `read_job_roles` | `changes:read` | Reads job roles with their responsibilities. |
| `read_people` | `changes:read` | Reads people: main role, extra roles, responsibilities, designation, manager (`person`, `search`). |
| `read_rounds` | `changes:read` | Reads hiring rounds. |
| `read_leave_types` | `changes:read` | Reads leave types. |
| `read_offers` | `changes:read` | Reads offer letters (`person`, `application`, `status`, `search`), hourly rate in paise. Admin key only. |
| `read_offer_templates` | `changes:read` | Reads the offer letter template: sections, fields, defaults. Admin key only. |
| `read_holidays` | `changes:read` | Reads holidays (`year`). |
| `read_shifts` | `changes:read` | Reads shifts and shift patterns. |
| `read_checkin_places` | `changes:read` | Reads offices and the check-in place settings. |
| `read_templates_full` | `changes:read` | Reads task templates with their repeats. |
| `read_access_roles` | `changes:read` | Reads access roles with their permissions and holders. Admin key only. |
| `read_access_presets` | `changes:read` | Reads the permissions each job role, designation and department gives. Admin key only. |
| `read_person_access` | `changes:read` | Reads what one person may do and why (`person`). Admin key only. |
| `read_access_holders` | `changes:read` | Reads who holds one permission (`code`), and where it comes from. Admin key only. |
| `read_worktime_rules` | `changes:read` | Reads the work time switches the admin set per person (unanswered cards, window kind). Admin key only. |
| `read_departments` | `changes:read` | Reads departments with their parent, head and status (`status`, `search`). |
| `read_grades` | `changes:read` | Reads grades with their rank and salary band (paise). The band shows only to keys with pay access. |
| `read_role_changes` | `changes:read` | Reads job role changes (`person`, `status`) with their before and after values. |
| `read_day_windows` | `changes:read` | Reads the work time window of each day (`person`, `from`, `to`; IST days, minutes from midnight). |
| `read_employment_types` | `changes:read` | Reads employment types: pay kind (marks or hours), switches, holders. Admin key only. |
| `read_new_person_choices` | `changes:read` | Reads the types for adding a person (`payKind`, `payKindMeans`), job roles, next code. Admin key only. |
| `read_worktime_cards` | `records:read` | Reads work time cards: overtime windows, late runs, corrections (`id`, `person`, `status`, `kind`, ...). |
| `read_past_days` | `records:read` | Reads the hours entered for days of one person (`person`, `from`, `to`). One page. |
| `read_no_window_people` | `records:read` | Reads people with no work time window (`from`, `to`, `person`). One page. |
| `read_candidates` | `records:read` | Reads hiring candidates (`q`, `round`, `status`). One page. |
| `read_applications` | `records:read` | Reads hiring applications (`id`, `person`, `round`, `status`). One page. |
| `read_leave_balances` | `records:read` | Reads leave balances in days (`person`, `as_of`). One page. |
| `read_leave_requests` | `records:read` | Reads leave requests (`person`, `status`, `from`, `to`). One page. |
| `read_attendance_days` | `records:read` | Reads the one record of each day of one person: mark or hours (`person`, `from`, `to`). One page. |
| `read_sandwiches` | `records:read` | Reads absences not informed on time, the sandwich rule (`person`, `state`, `from`, `to`). One page. |
| `read_wallet_hours` | `records:read` | Reads the hours of hourly people, paid into the wallet (`person`, `from`, `to`), paise. One page. |
| `read_checkins` | `records:read` | Reads check-ins without the photo (`person`, `status`, `from`, `to`). One page. |
| `read_roster_days` | `records:read` | Reads roster day plans (`person`, `from`, `to`). One page. |
| `read_pay_runs` | `records:read` | Reads pay runs (`id`, `kind`, `status`), money in paise. Admin key only. One page. |
| `read_salary_structures` | `records:read` | Reads salary structures (`person`), money in paise. Admin key only. One page. |
| `read_presence` | `records:read` | Reads who is online, or one person's timeline for one day (`person`, `day`). |
| `read_tests` | `records:read` | Reads the test library, or who sat which test (`view`, `person`, `status`). One page. |
| `read_targets` | `records:read` | Reads the targets of one person (`person`). |
| `read_letters` | `records:read` | Reads letters issued to people (`person`). Titles and status only. One page. |
| `read_documents` | `records:read` | Reads the documents of one person (`person`). Names and status only. One page. |
| `draft_changes` | `changes:draft` | Drafts one change set (title, reason, items). Nothing changes until a person approves it. |
| `get_change_set` | `changes:draft` | Reads one set you drafted, with the lines and status of each item. |
| `list_change_sets` | `changes:draft` | Lists the sets you drafted, newest first. |
| `withdraw_change_set` | `changes:draft` | Withdraws a set that still waits for review. |
Every POST carries a new `Idempotency-Key` (a UUID for each tool call), so a repeated call does not make a second draft.
### Ask Claude to change settings
You do not write JSON. You ask in plain words, and Claude does the steps:
1. You say: "Give Ravi the extra job role Sales and make Neha his manager. Also set the notice period to 45 days."
2. Claude reads the current state (`list_change_areas`, `read_people`, `read_settings`). It never guesses.
3. Claude drafts **one set** with `draft_changes`. Each change has its own reason. A thing the request needs that does not exist yet (a new department, a new person, a new access role) is made by an earlier change of the same set, so one request is one set to approve.
4. The portal answers with the plain lines of each change. Claude shows them to you.
5. You open **Changes to review** in the portal. You approve or reject each line. You can undo a line you approved.
6. Claude calls `get_change_set` and tells you what was applied.
Nothing changes until you approve in the portal. Only the admin's key may draft money and offer letters. Other keys are refused money, the admin account and executive roles, so
change those in the portal itself. If a part of the portal cannot be drafted yet, Claude says:
"This part of the portal cannot be changed by draft yet."
The employment type decides how a person is paid: its pay kind is `marks` (paid by the mark of each day) or `hours` (paid
by the hour into the wallet). An offer for an hours type carries `hourly_rate_paise`. The admin's key may draft a type and its pay kind in `employment_types`. A key never decides a mark: the admin's
key may draft a day in `past_days`, and the day is marked only when the admin approves it.
### A main task with sub-tasks
Each draft in `draft_tasks` takes `title`, and optionally `templateKey` or `body`, `notes`, `priority`, `dueAt`, `category`,
`doneWhen` (lines), and one of:
- `ref` plus `parentRef`: give the main task a `ref`; each sub-task names it in `parentRef` and comes after it in the list.
- `parentId`: hang the draft under a task that already exists.
A sub-task takes its main task's category when it has none. When the admin approves the batch, the tree stays: the main
tasks go to the person or pool the admin picks, and the sub-tasks can wait so the admin gives each one later.
## Prompts
- `write_test_plan` (optional `subject`) explains the plan JSON format (areas, cases, id, title, priority, device
`phone|laptop|both`, url, preconditions, steps, expected, screenshot) and the writing rules, then the agent sends the plan
with `draft_checklist`.
- `plan_growth_work` (optional `goal`, `category`) explains how to plan business work as main tasks with sub-tasks in the
portal's words: one result per task, "What to hand in" in the notes, a `doneWhen` a reviewer can check, numbers as starting
values. Then the agent sends it with `draft_tasks`.
- `change_portal` (optional `what`) tells the agent the flow: read first, draft one set for each topic, give each item a reason,
show you the lines the portal returned, and tell you to approve on Changes to review.
Each draft waits for a person to approve it in the portal.
## Errors
When the portal refuses a call, the agent gets the portal's error code, its message and every `details` path (for example
`drafts[3].parentRef`), so it can fix the input and send again. Three statuses add a plain hint:
- `401`: the key is wrong, ended or revoked. Make a new key on the Profile page.
- `403`: the key lacks a scope, or you lack the right. Make a new key with the scope.
- `429`: too many calls. Wait a minute.
## Security model
- **It runs on your computer.** The server is a local program. The agent talks to it over stdio, and it talks to the portal.
- **The key goes over https only.** A plain http address is refused, except `localhost`. A redirect is never followed, so the
key is never sent on to another address.
- **Portal text is data.** Task text and notes are written by people. The server tells the agent to read them as data, never
as instructions. Review what an agent drafts before you approve it.
- **The key stays in the header.** The server sends the key only as an `Authorization: Bearer` header. It never writes the
key to a log, an error or a URL.
- **The key acts as you, cut to its scopes.** A key never has more rights than the person who made it.
- **The agent can only make drafts and notes.** It cannot approve, assign, change a task, pay, send mail or delete.
- **A key drafts changes; only a person approves them in the portal.** No tool approves, applies or undoes a change set.
The portal refuses money, the admin account and executive roles to other keys, even as a draft. Only the admin approves the items only the admin's key could draft.
- **A person approves every draft.** Nothing becomes a task until a person approves it in the portal.
- **You can revoke a key at any time.** Open the portal Profile page and revoke the key. It stops working at once.
- **Report a vulnerability in private.** Follow [SECURITY.md](./SECURITY.md). Do not open a public issue.
## Develop
```bash
pnpm install
pnpm lint # biome
pnpm typecheck # tsc
pnpm test # unit tests with a fake fetch (this package is a client of an HTTP API)
pnpm build # tsup, writes dist/
pnpm check:dist # builds and fails when dist/ differs from the commit
COB_PORTAL_URL=... COB_PORTAL_KEY=... pnpm test:integration # real portal, read-only; skips when unset
```
### Contributions
Code contributions are by invitation only, because the server follows one private portal. Bug reports are welcome as
[issues](https://github.com/callobuzz/cob-portal-mcp/issues). Report a security problem in private, as
[SECURITY.md](./SECURITY.md) says.
### Release
1. Change the code and the tests. Bump `version` in `package.json` and `VERSION` in `src/core.ts`.
2. `pnpm lint && pnpm typecheck && pnpm test && pnpm build`.
3. Commit the source and `dist/` together. `pnpm check:dist` must pass after the commit.
4. Tag the commit `v<version>` and push the tag, so people can pin it.
This package does not depend on `cob-mcp-cli-kit`, as `cob-rag-mcp` does not. It uses the MCP SDK directly.
## Changelog
[CHANGELOG.md](./CHANGELOG.md)
## Licence
[MIT](./LICENSE). Copyright 2026 Callobuzz. Built by [Call O Buzz Services](https://callobuzz.com).
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues