# Audio Bee KB — MCP Connection Guide

Connect the Audio Bee knowledge base to Claude (Code, Desktop, claude.ai) or any
MCP client, so Claude can run **grounded searches** against our real docs —
carrier profiles, error codes, runbooks, conventions, Asana pipeline state, and
meeting notes — instead of guessing.

Server: **https://kb.dataweav.com**

---

## 1. What the KB MCP is

The KB exposes a small set of **read-only search tools** over Anthropic's Model
Context Protocol (MCP). Once connected, Claude can call them mid-conversation to
pull evidence straight from our corpus and answer with citations instead of from
memory.

The six tools:

| Tool | What it does |
| --- | --- |
| `kb_search` | Hybrid search across the whole KB (full-text + vector + title match, recency-boosted). Your general-purpose "find me docs about X". |
| `kb_carrier` | Look up a specific carrier / payer profile (scraping-docs carrier pages). |
| `kb_errors` | Look up an error code (e.g. `ERR-001`) and its meaning / handling from the error KB. |
| `kb_recent` | Show the most recently updated docs — good for "what changed lately". |
| `kb_sources` | List the sources feeding the KB (ClickUp Docs, GitHub, Asana, meetings) and their doc counts. |
| `kb_get` | Fetch one specific document in full by its id (usually after `kb_search` surfaces it). |

Everything is evidence-only: the tools return the actual document text and ids —
no invented answers.

---

## 2. Get your token

Every person connects with their **own** token. This is how the KB attributes
usage to you and enforces which projects you can see.

1. Log in to **https://kb.dataweav.com** with the username + password your admin
   gave you.
2. Open **"My Access Token"**.
3. Click **Generate**.
4. Copy the token — it starts with `kbk_` and is **shown only once**.

Keep it somewhere safe (a password manager). If you lose it, just click
**Generate** again — this produces a new token and **immediately invalidates the
old one** (any client still using the old token will start getting 401s, so
update them too).

> Accounts are **admin-invite-only** — there is no self-signup. If you don't have
> a login, ask an admin to create one for you.

---

## 3. Connect in Claude Code (CLI)

Run this once, substituting your real token. A bearer header is preferred
because it keeps credentials out of URLs and browser/proxy history:

```bash
claude mcp add --transport http audiobee-kb https://kb.dataweav.com/mcp/ \
  --header "Authorization: Bearer YOUR_kbk_TOKEN"
```

Then verify:

```bash
claude mcp list
```

Expect to see `audiobee-kb` with a **✔ Connected** status.

Test it in a Claude Code session:

```
use audiobee-kb: what's ERR-001?
```

Claude should call `kb_errors` and answer from the actual error KB.

---

## 4. Connect in claude.ai / Claude Desktop (online)

1. Open **Settings → Connectors**.
2. Click **Add custom connector**.
3. If the connector offers an HTTP headers field, set the URL to
   `https://kb.dataweav.com/mcp/` and add:

   ```text
   Authorization: Bearer YOUR_kbk_TOKEN
   ```

   If it does not support headers, use the compatibility URL:

   ```
   https://kb.dataweav.com/mcp/?token=YOUR_kbk_TOKEN
   ```

4. **Save.**

> Query-token URLs are a compatibility fallback. The KB suppresses them from
> nginx access logs and redacts them in application access logs, but URLs can
> still be retained by client history or diagnostics. Prefer a bearer header
> whenever the client supports one, and never paste a connector URL into chat.

---

## 5. Connect in Cursor / other MCP clients

Any MCP client that speaks the **HTTP transport** should use:

```
URL: https://kb.dataweav.com/mcp/
Authorization: Bearer YOUR_kbk_TOKEN
```

Add it as a custom / remote MCP server with transport type **http** (sometimes
labelled "streamable HTTP" or "remote server"). If the client has no header
support, append `?token=YOUR_kbk_TOKEN` to the URL as a fallback.

---

## 6. Usage visibility

Every MCP retrieval you run through your token is **attributed to your login**. In the
web UI, open **"My Usage"** to see:

- your query history,
- per-tool and per-source breakdown,
- top queries and zero-result queries,
- an approximate **embedding-only** cost estimate.

That estimate excludes optional Anthropic answer synthesis and ingestion-time
distillation, so it is not a complete provider-billing total.

Admins can see everyone's usage; you only see your own.

---

## 7. Project access

Your account may be **scoped to specific projects**. If so, your searches only
return documents from those projects — anything outside your allowed list is
invisible to you (and to Claude, through your token).

Project is an optional request filter, not a saved preference. If no project is
specified, the KB searches all projects your account is allowed to access; it
does not currently store a per-user default project.

If you're missing results you expect to see, your scope may be too narrow — ask
an admin to widen your project access. (An empty / unset allowed-projects list
means you can see **all** projects.)

---

## 8. Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| **401 Unauthorized** | Token is wrong, or you regenerated it (old one stopped working). | Regenerate in **"My Access Token"** and update the connector URL everywhere you use it. |
| **"Failed to connect" (local / on-network)** | DNS or network path to `kb.dataweav.com` is unavailable. | Verify DNS/VPN connectivity and ask an admin for the current endpoint; do not pin an old server IP in `/etc/hosts`. |
| **Tools missing / connector shows disconnected** | Connector wasn't added, or was added with a stale token. | Re-run `claude mcp add …` (CLI) or re-add the custom connector with the current bearer token (query-token URL only if headers are unavailable). |
| **`claude mcp list` shows ✘ / not connected** | Bad URL or token. | Remove and re-add: `claude mcp remove audiobee-kb` then the `mcp add` command from §3. |

Still stuck? Ask an admin to confirm your account is enabled, your token is
current, and your project scope covers what you're searching for.