Team setup: QDG Knowledge Base MCP

What this connects to

The product is QDG Knowledge Base (QDG KB). The qdb.qdatasite.com name is the public host; it does not mean there is a separate product called “QDB KB”.

• Browser viewer: https://qdb.qdatasite.com/knowledge-base/
• MCP endpoint: https://qdb.qdatasite.com/mcp/qdg-kb
• QDG KB Viewer is the read-only website.
• QDG Knowledge Base MCP is the authenticated integration used by Codex and Claude Code.
• KN Docs is a separate documentation project whose pages can be stored in QDG KB.

The MCP service and database connection run centrally on Odin. Team members do not install Python, run a local MCP service, or receive MySQL credentials. They need only their assigned bearer token and the client configuration below.

Before starting

1. Request a named token from Robert. Tokens are assigned to a person or device so writes are attributable and an individual token can be revoked.

2. Receive it through the agreed private channel. Never paste a token into chat, documentation, source code, a Git repository, a ticket, or a shared configuration file.

3. On Windows, open Edit environment variables for your account and create:

   • Variable name: QDG_KB_TOKEN
   • Variable value: the token supplied by Robert

4. Close and reopen the MCP client after setting or changing the variable. Already-running programs do not inherit the new value.

The name QDG_KB_TOKEN is not the secret. It is the lookup name used by the client; the environment variable's value is the secret token.

Codex setup

Open the user configuration file:

%USERPROFILE%\.codex\config.toml

Add this block once:

[mcp_servers.qdg_kb]
url = "https://qdb.qdatasite.com/mcp/qdg-kb"
bearer_token_env_var = "QDG_KB_TOKEN"
default_tools_approval_mode = "writes"

Do not replace QDG_KB_TOKEN in the TOML with the token itself. Completely restart Codex, then use the MCP server list or /mcp to confirm that qdg_kb is connected. A simple read test is:

Check QDG Knowledge Base status and list its projects.

default_tools_approval_mode = "writes" allows tools marked read-only to run normally while keeping approval prompts for write-capable tools.

Claude Code setup

User-level setup (once per machine)

After setting QDG_KB_TOKEN, run this in PowerShell. The single quotes deliberately preserve the ${QDG_KB_TOKEN} reference; the raw token is not part of the command.

claude mcp add-json qdg_kb '{"type":"http","url":"https://qdb.qdatasite.com/mcp/qdg-kb","headers":{"Authorization":"Bearer ${QDG_KB_TOKEN}"}}' --scope user

Restart Claude Code and verify:

claude mcp get qdg_kb

Inside Claude Code, /mcp should show the server as connected.

Project-level alternative

To make the non-secret server definition part of a repository, add this .mcp.json at the project root and commit it:

{
  "mcpServers": {
    "qdg_kb": {
      "type": "http",
      "url": "https://qdb.qdatasite.com/mcp/qdg-kb",
      "headers": {
        "Authorization": "Bearer ${QDG_KB_TOKEN}"
      }
    }
  }
}

Each teammate still sets their own QDG_KB_TOKEN. Claude Code asks the user to trust a new project-scoped MCP definition before using it. Do not configure both user and project scopes unless there is a deliberate reason; duplicate definitions can be confusing.

Team documentation rule

Add the following policy to the repository's agent instructions (AGENTS.md, CLAUDE.md, or the equivalent project rules):

When completing a project handover, deployment, release, or material architectural or operational change, update the matching QDG Knowledge Base project through the qdg_kb MCP tools before reporting completion. Read the current page first and supply its current version when updating. Never publish credentials, tokens, private configuration, customer data, or other secrets. If no matching project or page exists, ask the project owner before creating one. If QDG KB is unavailable, state clearly that documentation publication remains outstanding.

This rule makes documentation part of assistant-led delivery. A manual Git commit made outside an assistant session does not invoke MCP or update the knowledge base automatically.

Day-to-day use

• Search or read QDG KB before relying on memory for project architecture, deployment or handover information.
• Read a page before updating it; QDG KB uses version checks to prevent silent overwrites.
• Write factual, reviewed documentation to the matching project and page.
• Do not create throwaway pages merely to test write access.
• Every successful write creates an immutable page version and records the actor assigned to the token.

Troubleshooting

• Missing QDG_KB_TOKEN: set the user environment variable and restart the client.
• 401 or authentication failure: check that the whole token was copied without leading/trailing whitespace. If it still fails, ask Robert to verify or replace the assigned token.
• Connection failure: confirm the endpoint is exactly https://qdb.qdatasite.com/mcp/qdg-kb and check whether the browser viewer is reachable.
• Write denied: confirm the assigned token is enabled for both read and write scopes.
• Version conflict: reread the current page, merge the intended change, and retry using the new current version. Never force an overwrite.

External client references

• Official Codex MCP documentation
• Official Claude Code MCP documentation