Connect an AI app

MCP is a standard way for an AI app to use another application’s tools. Here, the app connects to the running dtxWiki server, searches permitted knowledge, and can propose edits when you grant the required access. It does not open the database directly. The dtxWiki server must remain running.

Read the flow as a request and response: the app asks, dtxWiki checks access, and permitted results return to the app. Content returned to an external app may reach its model provider. This diagram explains the boundary; it is not a live connection or an automatic workflow.

You can use dtxWiki in your browser without connecting an AI app. The AI app’s own installation, account, subscription, or model usage is separate from dtxWiki. Connecting it does not enable dtxWiki’s optional Ask model provider.

Before you begin

Have your dtxWiki account, membership of the workspace you need, and the server’s MCP address. For a remote server, it is usually https://wiki.example.com/mcp.

The packaged client catalog includes Claude Code, Codex CLI, Gemini CLI, and Google Antigravity. Cursor and other compatible clients can use manual HTTP configuration when they support Streamable HTTP and PAT or OAuth authentication. This is not a claim that every client/version combination has completed a live connection test.

The configuration recipes and server behavior are verified separately from full native client round trips, which remain pending in the compatibility matrix. Confirm that your client can read the intended material in your environment before relying on the connection.

Choose the minimum access you need. A scope limits which kinds of tools a credential can call; workspace membership and role also apply. A read-only key cannot write, and a Viewer account cannot gain editing rights by requesting a stronger key.

If you use Codex or Claude Code inside VS Code, follow VS Code extensions after creating an access key. You can edit the configuration files without installing a separate CLI. If you have used export before and lost the connection after a restart, follow Save an environment variable before launching the extension again.

Route A: browser approval with OAuth

OAuth lets you approve a client in your browser without manually copying a PAT. Use it if your server and AI app support it; otherwise use Route B. The server needs HTTPS. For an internal CA, the browser and client must trust its root certificate.

1. In Settings → MCP access, check whether OAuth is available. If this server cannot offer it, the notice includes a Use an Access Key. link that takes you to Access key setup (Route B).
2. Select the AI client’s displayed setup command, or add the dtxWiki HTTPS MCP address from that client.
3. Follow the client’s sign-in prompt. Check the dtxWiki account, allowed workspaces, and scopes on the browser consent screen before approving.
4. Return to the client and perform the read checks below.
5. Confirm the app appears under Approved apps in OAuth apps. Use Edit workspaces to change its reach or Revoke to remove consent later.

The app’s card shows its state beside the name, its Permissions, and its Allowed workspaces: up to two names, plus +N when there are more. Select a name or +N to open the full, searchable list. Below them are Granted, Last used and Session expiry. When no sign-in session remains, Session expiry reads Reauthorization required; sign in again from the client to continue.

For the CLI surfaces documented by this snapshot:

# Claude Code
claude mcp add --scope user --transport http dtxwiki https://wiki.example.com/mcp
claude mcp login dtxwiki

# Codex CLI
codex mcp add dtxwiki --url https://wiki.example.com/mcp --oauth-client-registration auto
codex mcp login dtxwiki --oauth-client-registration auto

These commands show registration and login syntax from the checked client surfaces. Browser approval, refresh, and authenticated tool calls must still be checked with your installed client. Gemini CLI and Antigravity have no completed dtxWiki OAuth round-trip evidence in v0.2.1; use PAT setup until your environment has been validated. If the server disables automatic registration, use a compatible HTTPS URL client identifier or the access-key route offered in Settings.

Route B: create an access key

An access key is a Personal Access Token (PAT): a secret that authorizes an app to act through your account.

1. Open Settings → MCP access and find Access key setup.
2. Choose the client and enter a Key name you can recognize, such as “Research laptop”. The name must fit on one line and can have up to 128 characters. If you choose Other MCP client, also enter its AI app display name (up to 160 characters).
3. Under Workspaces this key may reach, your default workspace is already selected. To change the selection, choose View and select workspaces. In the Allowed workspaces dialog:
   • Search by workspace name or slug. The list shows only workspaces you are a member of, your default workspace first, eight per page; use Previous and Next to change pages.
   • Click a row to select or clear it. Select this page selects or clears every workspace on the current page, and Clear all selections clears everything. Selected items (N) shows only your selection; Show all workspaces (N) returns to the full list.
   • Choose Apply N selected to keep the selection, or Cancel to discard it. One key can reach up to 256 workspaces.
4. Review the displayed permissions: Read, Write, and Run AI. Start with Read for lookup; Context changes and reference registration require Write and an Editor/Owner membership. Run AI alone does not allow Context editing.
5. Choose Generate access key, copy the key when it is shown once, and follow the displayed client setup. Keep the key out of public repositories, issues, and screenshots.

Keys created in Settings expire after 90 days; the form has no other expiry choice.

Searching or changing pages keeps the workspaces you already selected. Check Selected items (N) before applying the selection. If the dialog shows Could not load workspaces., choose Retry and wait for the results before changing access.

The key’s allowed-workspace list is account-wide, not limited to the workspace currently shown. To change it later without registering the client again, choose Edit workspaces on the key’s card. The dialog it opens, Workspaces for followed by the key’s name, has the same search and pages, and a status line counts the workspaces you added and removed. Removing a workspace stops the key’s access to it immediately; work already in progress is kept. Save workspaces is available only when the selection has changed and is not empty. A workspace you are no longer a member of is marked No membership under Selected items and can only be removed. OAuth apps use the same dialog.

A membership alone is not enough: requesting a workspace outside the credential’s allowed list returns token_workspace_denied.

Native client examples

Use your actual server address and credential. The placeholders below are not usable tokens. The UI-generated recipe is preferable when it accounts for your server and selected shell.

Claude Code stores the PAT in its local configuration when using a bearer header:

claude mcp add --scope user --transport http dtxwiki https://wiki.example.com/mcp \
  --header "Authorization: Bearer <YOUR_DTXWIKI_PAT>"

Codex CLI reads the PAT from an environment variable. This Bash example sets it only for the current terminal and apps launched from it. Enter it without placing its literal value in command history:

read -r -s -p 'dtxWiki access key: ' DTXWIKI_MCP_PAT
printf '\n'
export DTXWIKI_MCP_PAT
codex mcp add dtxwiki --url https://wiki.example.com/mcp \
  --bearer-token-env-var DTXWIKI_MCP_PAT

The command saves the variable name, not its value. Start codex from this terminal to use the temporary value. Closing the terminal or restarting the computer loses that value. Follow Save an environment variable to make it available on later launches. If your organization provides a secrets tool, use its supported way to supply the variable.

Gemini CLI stores an environment-variable reference in its header setting. With DTXWIKI_MCP_PAT already available:

gemini mcp add --scope user --transport http \
  --header 'Authorization: Bearer $DTXWIKI_MCP_PAT' \
  dtxwiki https://wiki.example.com/mcp

The single quotes preserve $DTXWIKI_MCP_PAT for Gemini’s configuration expansion. Its JSON endpoint field is httpUrl.

Google Antigravity can be configured by the optional helper below or by an HTTP entry in ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "dtxwiki": {
      "serverUrl": "https://wiki.example.com/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_DTXWIKI_PAT>"
      }
    }
  }
}

Merge the entry with your existing configuration; do not erase other servers. This stores the PAT in plain text, so protect the file and its backups. Expansion of $VAR inside persisted Antigravity headers is not verified. After restart, use the client’s /mcp surface to inspect status and perform a real read.

Cursor and other HTTP clients can use the following shape if accepted by that client:

{
  "mcpServers": {
    "dtxwiki": {
      "url": "https://wiki.example.com/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer <YOUR_DTXWIKI_PAT>"
      }
    }
  }
}

Windows and configuration locations

Use the Windows recipe offered by the setup screen. PowerShell uses a backtick for line continuation; a Bash command’s backslash is not interchangeable. For environment-based clients, follow the Windows user-variable steps before launching them. With the variable ready, the Codex registration command can be entered on one line in PowerShell:

codex mcp add dtxwiki --url https://wiki.example.com/mcp --bearer-token-env-var DTXWIKI_MCP_PAT

Client	Default user configuration
Claude Code	~/.claude.json; Windows %USERPROFILE%\.claude.json
Codex CLI	~/.codex/config.toml; uses $CODEX_HOME/config.toml if CODEX_HOME is set
Gemini CLI	~/.gemini/settings.json; Windows %USERPROFILE%\.gemini\settings.json
Antigravity	~/.gemini/config/mcp_config.json; Windows %USERPROFILE%\.gemini\config\mcp_config.json

Native registration does not require the dtxWiki Python package on your computer.

VS Code extensions

Open VS Code’s Extensions view (Ctrl+Shift+X on Windows/Linux, Cmd+Shift+X on macOS). Install the official Codex extension from OpenAI or Claude Code from Anthropic, then open its panel and complete its sign-in. That account sign-in and the dtxWiki access key serve different purposes. Installation details: Codex IDE extension, Claude Code in VS Code.

Choose the instructions for the extension you use. Each extension reads its own MCP configuration. VS Code’s built-in MCP setup for Copilot has a separate configuration.

Codex extension

1. Create an access key above, then complete Save an environment variable. Use the environment where the extension runs: Windows, macOS/Linux, or WSL.
2. Open your user configuration file in VS Code: ~/.codex/config.toml on macOS/Linux, or %USERPROFILE%\.codex\config.toml on Windows. Here ~ and %USERPROFILE% mean your user’s home folder. If the folder or file does not exist, create it. If you set CODEX_HOME, use the config.toml in that folder.
3. Add the following block and save. If [mcp_servers.dtxwiki] already exists, update it instead of adding a second block. Keep your other settings and replace the example server address.

[mcp_servers.dtxwiki]
url = "https://wiki.example.com/mcp"
bearer_token_env_var = "DTXWIKI_MCP_PAT"

4. Fully quit VS Code, then launch it with the saved variable available as described in the environment guide. Open the Codex panel and check its MCP server list, then perform the read check below.

The CLI and extension share MCP configuration when they use the same user and Codex home on the same host. If you already ran codex mcp add, check the existing entry. The TOML field above contains only the variable’s name; the extension still needs its value each time it starts. See OpenAI’s MCP configuration documentation.

Claude Code extension

If you already registered dtxWiki with claude mcp add --scope user ... --header "Authorization: Bearer <YOUR_DTXWIKI_PAT>", start a new extension conversation and inspect /mcp. This method stores the actual key in your local user configuration, so it does not need an environment variable on each launch. Protect that file.

To keep the key outside the project configuration and read it from an environment variable instead:

1. Complete Save an environment variable for the environment where Claude Code runs.
2. Open a trusted project in VS Code. At the project’s top level, beside files such as README.md, create .mcp.json. Include the leading dot. If the file already exists, merge the dtxwiki entry into its mcpServers object.
3. Save this configuration with your actual server address. Keep ${DTXWIKI_MCP_PAT} exactly as written; Claude Code substitutes the variable when it loads the configuration.

{
  "mcpServers": {
    "dtxwiki": {
      "type": "http",
      "url": "https://wiki.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${DTXWIKI_MCP_PAT}"
      }
    }
  }
}

4. Fully quit VS Code and relaunch it with the variable available. Open the same project, start a new Claude Code conversation, and review any project-server approval prompt. Type /mcp to inspect dtxWiki, then perform the read check below.

This .mcp.json applies to this project. An existing local or user registration with the same name can take precedence; check /mcp for the configuration in use before changing it. Pasting an actual key in place of ${DTXWIKI_MCP_PAT} stores that secret in the file. Also, a command such as --header "Authorization: Bearer $DTXWIKI_MCP_PAT" expands the value in the shell before registration and saves the actual key. See Claude Code’s configuration scopes and variable expansion.

For either extension, a variable set inside VS Code’s integrated terminal reaches commands launched from that terminal. It cannot update an extension that is already running. Follow the VS Code launch steps when a CLI works but the extension fails.

Optional dtxWiki setup helper

If you have installed the matching dtxWiki package, the helper backs up and updates supported local client configurations. Use one catalog ID: claude-code, codex, gemini-cli, or antigravity.

dtxwiki mcp register-http \
  --url https://wiki.example.com/mcp \
  --client codex \
  --token-env DTXWIKI_MCP_PAT

Add --dry-run to inspect the setup without changing the file. The helper reports whether it changed a configuration or only rendered instructions. Some clients store a plaintext PAT; read the warning and protect the file. Passing a token with --token can expose it in process arguments; prefer --token-env.

The helper reads an existing variable; it does not save that variable for future terminal sessions or computer restarts. For Codex, the written configuration still references DTXWIKI_MCP_PAT. Complete the environment setup as well.

Plain HTTP on this computer or a trusted LAN

The helper refuses a plain http:// address unless you add --allow-insecure-local. Even then it needs an access key (--token-env or --token) and accepts only these hosts:

• this computer: localhost, [::1], or a 127.x.x.x address such as 127.0.0.1;
• a private-network IP address written as numbers: 10.x.x.x, 172.16.x.x to 172.31.x.x, 192.168.x.x, or an IPv6 address in fc00::/7.

A host name such as wiki.lan, and every other address, still needs HTTPS. OAuth always needs HTTPS.

For a same-computer local trial:

dtxwiki mcp register-http \
  --url http://127.0.0.1:21080/mcp \
  --client codex \
  --token-env DTXWIKI_MCP_PAT \
  --allow-insecure-local

That URL works only on the computer running dtxWiki. For a trusted LAN trial, run the helper on the other computer with the server’s private IP address instead, for example when the server was started as described in LAN access:

dtxwiki mcp register-http \
  --url http://192.168.1.20:21080/mcp \
  --client codex \
  --token-env DTXWIKI_MCP_PAT \
  --allow-insecure-local

Plain HTTP sends the access key and every returned page unencrypted, so use it only for an evaluation on a network you trust. When DTXWIKI_PUBLIC_BASE_URL is set to such a private IP address, the access-key setup in Settings → MCP access shows the same HTTP address for Claude Code, Codex CLI, Gemini CLI and Antigravity; Other MCP client still needs HTTPS. dtxwiki mcp doctor --http also accepts these addresses, but its [b] tls handshake check always fails for http://, so its report ends with one or more checks failed even when [d] list_tools passes. Clients that connect over the internet need the server’s HTTPS address.

Check the connection before giving it more access

Ask the client, in your own words:

“Use dtxWiki to list the workspaces I can access. In the project workspace, find the published page about our meeting process and show its title and source. Do not change anything.”

Confirm that the workspace and content match what you can read in the browser. If you later permit writes, test a clearly named draft in a practice workspace and inspect its edit/review state in the browser. Editors and Owners can also open Chats, select the client’s call, and use its Inputs tab to check the workspace and, when shown, the page versions it used (Input version, Base version). A registration entry, a connection badge, or a successful server-side doctor result alone is not the same as a successful read or safe edit.

Check connection status in Settings

The Connected MCP clients card in Settings → MCP access lists the client identities that have called the workspace currently selected. Switch workspaces to see another workspace’s clients. Each client shows the state of its own credential, the access key or OAuth approval it used, beside its name:

State	Meaning
Credential valid	The access key or OAuth approval still works for this workspace.
Credential expired	The key has passed its expiry date, or the OAuth approval has no live session left.
Credential revoked	The key or OAuth approval was revoked, this workspace was removed from it, or its holder is no longer an active member of this workspace.
Check credential status	dtxWiki cannot tell which credential the client used, or that credential no longer exists. An older record is completed by the client’s next call.
Use blocked	An Owner disabled the client. This replaces the credential state.

A separate line shows the Owner’s setting, Use allowed or Use blocked. The times show Last used, then Key expiry for an access key or Session expiry for OAuth, which reads Reauthorization required when no session remains.

Use the MCP client state filter to show Available clients (use allowed and credential valid), Other states (everything else), or All; each choice shows its count. Owners can Disable an allowed client, which blocks its future calls but keeps its credential history, and can Reactivate or Delete client a blocked one. In v0.1.2, a client could still appear active after its key had expired or been revoked; after upgrading, such clients appear under Other states.

You can revoke keys and OAuth consents in Settings → MCP access. An expired key shows Expired beside its name and its past Key expiry date. Create a replacement and update the client; PATs are not automatically extended. To remove expired or revoked OAuth approval records, choose Review cleanup candidates under Connection history cleanup. The Clean up old connections dialog shows how many records it will remove; choose Clean up to confirm. Client identities and their call history stay. If you ask an operator about a key, give the UUID shown under Key details, never the key itself.

Read Privacy and safe sharing and Troubleshooting when access or certificate checks fail.

For custom integrations and tool instructions, continue to the API and MCP reference. It explains workspace discovery, the tool catalog, safe Context edits, pagination, and the versioned REST/MCP contracts.

Workspace targets and the 0.2 contract

After connecting, discover UUIDs with list_my_workspaces, then pass the selected workspace_id to guide and every later workspace-scoped tool or dynamic prompt. Edited key permissions apply to existing sessions on the next request. The contract is revision 29; refresh tool catalogs and read API/MCP changes. Inbox also provides key-expiry notices.

Tools by key permission

Displayed permission	Examples	Limits
Read	guide, search, fetch, read, get_index, read_agent_page	Only accessible documents. It does not include list_changes or list_requested_changes.
Write	Context create/edit, reference registration with cite, review submission and permitted change/review reads	Editor/Owner membership and state checks still apply. MCP exposes no approval tool.
Run AI	build_agent_input_bundle, write_agent_page_draft	Does not replace Write for Context editing. Check the required read permissions too.

The underlying umbrella scopes are mcp:read, mcp:write and mcp:agent; distinguish these diagnostic names from the form's labels. Server administration does not replace workspace membership.

Client plugins and skills

The product's integrations/claude-plugin, integrations/codex-plugin and integrations/agent-skills directories contain retrieval, conventions, authoring/review and maintenance instructions. Configure MCP first, then add the desired package through the client's plugin/skill installation mechanism. A plugin does not increase account permissions. Keep checking tool results and the actual review/publication state.

Sources: tool scopes, permission expansion, bundled integrations.

---

Version evidence: client setup instructions, client evidence limits, helper CLI, HTTP address rules, connection doctor, MCP access settings, workspace picker, credential states, key and workspace limits.