unntak-mcp

local MCP server for the unntak.no agent API. it lets an MCP client read, create, time, comment on, and complete tasks inside an agent's tag scope.

all supported accounts are end-to-end encrypted. encrypted task content is decrypted only inside this local process. unntak.no receives the inner scoped API credential and ciphertext; the master key from the combined token is never sent to the server.

setup

1. in unntak.no, open :) → settings → agents and create an agent token. copy the complete token once. encrypted tokens start with unntak-agent-v2..
2. add the local server to your MCP client:

read -s "UNNTAK_TOKEN?Agent token: "
echo
claude mcp add --scope user unntak \
  -e UNNTAK_TOKEN="$UNNTAK_TOKEN" \
  -- uvx unntak-mcp
unset UNNTAK_TOKEN

for a local Unntak instance, also add -e UNNTAK_URL=http://localhost:8000 before --.

the complete token is a password and, for encrypted accounts, also contains the key needed to read the agent's task content. never commit it, paste it into issues, or include it in logs. revoke it in Unntak settings if it is exposed.

only combined unntak-agent-v2. tokens are accepted.

upgrade an existing installation

uvx installs published versions on demand. force it to refresh the cached package, then verify the token and E2EE decryption:

read -s "UNNTAK_TOKEN?Agent token: "
echo
export UNNTAK_TOKEN
uvx --refresh-package unntak-mcp unntak-mcp --check
unset UNNTAK_TOKEN

restart the MCP client afterwards. to replace a revoked token:

read -s "UNNTAK_TOKEN?New agent token: "
echo
claude mcp remove --scope user unntak
claude mcp add --scope user unntak \
  -e UNNTAK_TOKEN="$UNNTAK_TOKEN" \
  -- uvx unntak-mcp
unset UNNTAK_TOKEN

then confirm the connection:

claude mcp list

connection check

the check is read-only. success prints the decrypted agent name, scope, and open task count:

{"agent":"007","open_tasks":0,"scope":"agent;007"}

agent flow

the server sends these rules to the model automatically on connect: check list_tasks at session start, read a task and its comments before working, start the timer, comment progress, and always complete or stop the task before ending the session.

tools

• whoami — agent name, scope, and open task count
• list_tasks — open tasks in the agent's scope
• get_task — one task with comments
• add_task — create a scoped task
• start_task / stop_task — operate the live focus timer
• log_time — log a block of seconds without the live timer
• comment — comment under the agent's name
• complete_task — finish a task and archive it

encryption

combined v2 tokens use AES-256-GCM task and comment payloads, authenticated agent metadata, and HMAC-SHA-256 blind scope tokens. plaintext tokens and responses are rejected.

the combined token is split locally. only its inner API token is used as the HTTP bearer credential. ciphertext, keys, and combined tokens are removed from MCP tool results and error messages.

skill/SKILL.md documents the agent workflow for clients with skill support. encrypted accounts must use this MCP package or another compatible local E2EE client because the combined token must never be sent whole as an HTTP bearer.

development

uv sync --locked --dev
uv run pytest
uv build --no-sources

test the built wheel instead of the editable source:

UNNTAK_TOKEN=unntak-agent-v2... \
  uvx --from ./dist/unntak_mcp-0.3.0-py3-none-any.whl unntak-mcp --check

release

CI tests Python 3.11 and 3.14, builds both distributions, and smoke-tests the built artifacts. publishing uses the pypi GitHub environment and PyPI trusted publishing, so no PyPI password is stored in GitHub.

create a tag matching the package version only after CI passes:

uv run pytest
uv build --no-sources
git tag -a v0.3.0 -m v0.3.0
git push origin v0.3.0

the tag publishes to PyPI. server.json can then be published separately to the official MCP registry for discovery.