cob-portal-mcp

Connect your AI agent to the Call O Buzz portal

Your agent reads the team's tasks and drafts new ones. Nothing becomes real work until a person approves it in the portal.

  • Drafts and notes only. It cannot assign, approve, pay, send mail or delete.
  • Runs on your computer with your own key, cut down to the scopes you pick.
  • Claude Code, Claude Desktop or any MCP client. Node.js 22 or newer.

Set it up in three steps

  1. Make a key in the portal

    Profile, then API keys. Two-step sign-in must be on. Tick only the scopes you need (which ones). The portal shows the key once, so copy it then.

  2. Add the server to your agent

    Terminal
    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_config.json, inside "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 "Copy MCP setup" button gives this with your address and key filled in.

  3. Ask the agent to run whoami

    It answers with your name, the key's name, its scopes and its end date. A wrong key gets a plain message that says what to do.

How it works

A good agent can plan work, write a test plan or break a goal into tasks. The portal is where the team tracks that work. This server connects the two and keeps a person in charge.

  1. The agent reads

    It lists tasks, templates and categories, and reads one task with its steps, answers and notes.

  2. The agent drafts

    It sends draft tasks, a main task with sub-tasks, or a test plan as a check list. It can also leave a note.

  3. A person approves

    The drafts wait in the portal. A person approves or rejects each one and chooses who gets the task.

What the agent can and cannot do

The server offers only these actions. The portal checks every one again, so a changed server cannot do more.

It can

  • Read tasks, with their steps, answers and noteswork:read
  • Read task templates and categorieswork:read
  • Read the results of a test check listchecks:read
  • Send draft tasks, a main task with sub-taskswork:draft
  • Send a test plan as a check list draftwork:draft
  • Write a note on a task, marked as written through the keywork:comment

It cannot

  • Approve a draft, its own or anyone's
  • Assign a task or choose who gets it
  • Change or close a task
  • Pay, or touch salary and invoices
  • Send mail or messages
  • Delete anything

Every draft waits for a person. In the portal, someone approves or rejects each draft and decides who gets the task. Sub-tasks can wait so they are given out one by one later.

Pick the scopes for the job

A key acts as you, cut down to the scopes you tick. It never has more rights than you. Tick the fewest that do the job.

You want the agent toTickTools it gets
Answer questions about the workwork:readlist_tasks, get_task, list_templates, list_categories
Plan work and draft taskswork:read + work:draftthe four above, and draft_tasks, list_drafts, get_draft
Write a test planwork:read + work:draftthe same, and draft_checklist
Leave notes on tasksadd work:commentadd_comment
Read test resultsadd checks:readget_check_results

whoami needs no scope. The server asks the portal for the key's scopes at start and offers only the tools they allow, so a missing tool means a missing scope.

How your key is protected

The key acts as you, so the server treats it with care.

  • Https onlyA plain http address is refused, except localhost for a test portal on your own computer.
  • No redirects followedIf the address sends the call somewhere else, the call stops, so the key never goes to another server.
  • Only in the headerThe key travels as an Authorization: Bearer header. It is never written to a log, an error or a web address.
  • Portal text is dataTask text and notes are written by people. The server tells the agent to read them as data, never as instructions.
  • One retry, one draftEvery send carries a new Idempotency-Key, so a repeated call never makes a second draft or note.
  • Revoke at onceRevoke the key on the portal Profile page and it stops working on the next call.

The eleven tools

Tools marked writes send something to the portal. The rest only read.

ToolScopeWhat it does
whoaminoneShows you, the key's name, its scopes and its end date.
list_taskswork:readLists your tasks or your team's, by status, category or parent task.
get_taskwork:readReads one task with its steps, answers, notes, category and sub-task count.
list_templateswork:readLists the published task templates, with their category.
list_categorieswork:readLists the task categories the portal offers.
get_check_resultschecks:readReads the test runs and skips of a check list task. File names only, no files.
draft_taskswriteswork:draftSends a batch of draft tasks. Use ref and parentRef for sub-tasks, or parentId for a task that exists.
draft_checklistwriteswork:draftSends a test plan as one draft with a check list.
list_draftswork:draftLists the draft batches you sent.
get_draftwork:draftReads one draft batch, with the state of each draft.
add_commentwriteswork:commentWrites a note on a task, marked as written through the key.

Reference

Prompts

write_test_plan
Explains the plan format and the writing rules, then the agent sends the plan with draft_checklist. Optional subject.
plan_growth_work
Plans business work as main tasks with sub-tasks, each with one result and a "done when" a reviewer can check. Optional goal and category.

Settings

COB_PORTAL_URL needed
The portal address, as the Profile page shows it. Https only.
COB_PORTAL_KEY needed
Your key. It starts with cob_.
COB_PORTAL_TIMEOUT_MS optional
How long to wait for one answer. 30000 by default, at least 1000.

When a call fails

401: the key was not accepted
It is wrong, ended or revoked. Make a new key on the Profile page.
403: not allowed
The key lacks a scope, or you lack the right. Make a key with the scope.
429: too many calls
Wait a minute, then try again.

Other ways to run it

Stay on one version
Write cob-portal-mcp@0.2.1 in place of cob-portal-mcp.
Straight from GitHub
Write github:callobuzz/cob-portal-mcp. The built files are in the repository, so nothing is built on your computer.
A folder copy
Clone the repository and run node <folder>/dist/cli.js. On Windows, write the path with forward slashes.

Questions

Do I need a portal account?

Yes. The server works only with the Call O Buzz portal. You need an account with two-step sign-in, the right to make API keys, and the portal address. There is no hosted version.

Can the agent approve its own drafts?

No. It can only make drafts and notes. A person approves every draft in the portal and decides who gets the task.

Where does my key go?

Only to the portal address you set, in the Authorization header. Keep it out of files you commit, and revoke it on the Profile page if a laptop is lost.

Why does my agent see fewer tools than this page lists?

The key lacks a scope. Run whoami to see the key's scopes, then make a new key with the scope you need.

Can I add features or send code?

Code contributions are by invitation, because the server follows one private portal. Bug reports are welcome as GitHub issues.

How do I report a security problem?

Do not open a public issue. Follow SECURITY.md.

Let your agent draft the work. A person approves it.

Open source under the MIT licence, built by Call O Buzz Services for its own portal.