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.

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.

In Settings → MCP access, check whether OAuth is available.
Select the AI client’s displayed setup command, or add the dtxWiki HTTPS MCP address from that client.
Follow the client’s sign-in prompt. Check the dtxWiki account, allowed workspaces, and scopes on the browser consent screen before approving.
Return to the client and perform the read checks below.
Confirm the app appears in OAuth apps. Use Edit workspaces to change its reach or Revoke to remove consent later.

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.1.2; 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.

Open Settings → MCP access and find Access key setup.
Choose the client and name the key so you can recognize it, such as “Research laptop”.
Select one or more allowed workspaces and review the scopes. For looking up knowledge, start with mcp:read. Writing needs the appropriate additional scopes and an Editor/Owner membership.
Choose an expiration. Web-issued keys default to 90 days; available choices are 30, 90, 180, 365 days, or no expiry.
Generate the key, copy it when shown once, and follow the displayed client setup. Keep the key out of public repositories, issues, and screenshots.

The key’s allowed-workspace list is account-wide, not limited to the workspace currently shown. Edit it later without registering the client again. 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. In Bash, enter it without placing its literal value in command history:

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

The same environment variable must be available when you launch the client. If your approved secrets tool can provide it, use that tool instead of writing the literal secret in a shell profile.

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, $env:DTXWIKI_MCP_PAT must be set securely in the environment that launches them.

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.

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.

For a same-computer local trial only, PAT registration can use the explicit insecure-local opt-in:

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 from the computer running dtxWiki. Remote clients need the server’s reachable 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. 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.

You can revoke keys and OAuth consents in Settings → MCP access. If a key expires, create a replacement and update the client; PATs are not automatically extended. 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.

Version evidence: client setup instructions, client evidence limits, helper CLI.

Before you begin​

Route A: browser approval with OAuth​

Route B: create an access key​

Native client examples​

Windows and configuration locations​

Optional dtxWiki setup helper​

Check the connection before giving it more access​