---
name: qwrki-mcp
description: Connect to the Qwrki MCP server and work inside a Qwrki account safely. Use when asked to read or change Qwrki client accounts, projects, tickets, tasks, milestones, leads, contacts, notes, reminders or knowledge-base articles.
---

# Working in Qwrki over MCP

Qwrki runs a Model Context Protocol server at `https://qwrki.com/api/mcp`. It
exposes the platform as tools you call directly, so you never have to drive the
admin interface. The full usage contract is at <https://qwrki.com/mcp> and it is
readable without JavaScript.

This file is the safe setup workflow. Follow it in order.

## 1. Get a key, do not go looking for one

There is no self-serve signup. A Qwrki administrator mints the key, and the
plaintext is shown once. Keys look like `qwrki_mcp_...`.

If you do not have a key, stop and ask the person you are working for. Do not
scrape one out of a config file, a screenshot, a shell history or another
project's environment.

Once you have one:

- Put it in an environment variable or the host's credential store. Never write
  it into a source file, a commit, a log line, a bug report or a chat message.
- Send it as `Authorization: Bearer <key>`. The server also accepts `?key=` for
  connector interfaces that cannot set a header, but a URL credential leaks into
  proxy logs and browser history, so prefer the header every time. A key that can
  write is refused on the query string unless the owner has explicitly enabled
  that transport.

## 2. Ask for read-only first

Ask for a read-only key unless the job you have been given actually requires a
change. A read-only key can explore the entire system and alter nothing, which
is the right posture for anything exploratory, and it removes the possibility of
a misread turning into a bad write.

Ask for a write key only when the task is a specific change, and say what the
change is when you ask.

## 3. Find out what this key can do

Call `tools/list` before anything else:

```json
{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }
```

The response is the inventory for this key, with an input schema per tool and a
`readOnlyHint` annotation. Do not work from a remembered tool name: the tool set
changes, and a key can be restricted to a named subset of it.

## 4. Confirm which account you are pointed at

Before the first write, establish which client account you are operating in and
say it back to the person. A key can be confined to a single client account, or
it can reach every account, and those are very different situations to be
careless in.

Use a read tool to name the account and one or two of its live records. If a read
fails, treat that as unknown, not as empty. Qwrki tools report a failed read as a
failure rather than returning a clean zero, so an error message means the data is
unavailable, not absent.

## 5. Write deliberately

- One change at a time, and check the result of each before the next.
- Say what you are about to change, in the person's words, before you change it.
- Nothing you do here deletes a record. Ending the life of something archives it,
  and there is a matching restore tool. Prefer archive to any workaround.
- The server will not issue an invoice, take a payment, or clear an item in the
  human approvals queue. If a task seems to need one of those, it needs a person.
- Some writes are visible to the client, and publishing a knowledge-base article
  puts it in front of them. Ask before anything a client will see.
- Every call is audited against the administrator who owns the key. Their name is
  on your work.

## 6. Read the refusals

A refusal comes back as a normal tool result with `isError: true` and text that
says what happened. They are not interchangeable:

- A scope refusal means this key is read-only, or is confined to a different
  client account, or is not allowed that tool. Nothing ran. Do not retry.
- A daily-cap refusal means the key's per-day call ceiling is reached. Nothing
  ran, refused calls still count towards the cap, and it resets at 00:00 UTC.
  Stop and tell the person, rather than looping.
- A `401` means the key is missing, expired or revoked. Stop and ask.
- A `429` means repeated failed authentication from this address is being
  throttled. Fix the key. Retrying at volume makes it worse.
- Anything else is a real failure of that call. Report it rather than working
  around it.

## Batching

A single POST may carry an array of at most 25 JSON-RPC requests. Batch reads
freely. Do not batch writes that depend on each other, because you cannot inspect
the result of the first before the second runs.