# Doit MCP Setup

> Set up the DoiT MCP server in supported clients and verify the connection flow. Use when the agent needs to configure ChatGPT, Claude, Claude Code, Codex, Cursor, or Gemini CLI for DoiT MCP access, produce the correct connection snippet, explain required credentials, or troubleshoot why a DoiT MCP client is not connecting.

- Skill: `doitintl/doit-mcp-setup` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add doitintl/doit-mcp-setup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/doitintl/doit-mcp-setup/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: doitintl (https://skillmd.com/u/doitintl)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/doitintl/doit-mcp-setup

---


# DoiT MCP Setup

Set up DoiT MCP clients automatically when possible. For clients with writable config files, collect the required credentials and write the config directly. For clients that require manual UI steps, guide the user through each step.

Do not invent alternate URLs, auth methods, or config keys.

## Reference Files

- `templates/` — ready-to-use config snippets for each automated client. Read and merge from these files instead of reconstructing config from prose.
- `references/troubleshooting.md` — expanded troubleshooting table with client-specific notes. Read this when the user reports a connection issue.

## Setup Flow

1. Ask the user which client to configure: ChatGPT, Claude (web), Claude Code, Codex, Cursor, or Gemini CLI.
2. Confirm the user has the `Billing Profiles Admin` permission in DoiT.
3. Determine the auth flow before asking for credentials:
   - ChatGPT: ask for the DoiT API key and DoiT Customer ID because the OAuth flow prompts for them.
   - Claude (web), Claude Code, Codex, Cursor, and Gemini CLI: use the remote OAuth flow. Do not ask for an API key up front.
4. Follow the client-specific section below to configure the MCP server.
5. After MCP setup, always install the DCI CLI — follow the `DCI CLI Installation` section. This applies to all clients.

Do not write placeholder credentials into config files.

## Automated Clients

These clients have local config files the agent can write directly. Use the template files in `templates/` as the source — read the template, merge into the existing config, and write back.

### Claude Code

Config file: `~/.claude.json`
Template: `templates/claude-code.json`
Plugin registry: `~/.claude/plugins/installed_plugins.json`

1. Read `~/.claude/plugins/installed_plugins.json`.
2. Check whether `doit-mcp@doit-mcp-skills` exists in the `plugins` object. If it does, the plugin is already installed — confirm to the user that the MCP server is already configured via the plugin and skip the remaining steps. Tell the user to run `/mcp` in Claude Code to verify the server is connected, then click `Authorize` if it is not yet authorized.
3. If the plugin is not installed, proceed with manual MCP install:
   - Read `~/.claude.json`.
   - Read `templates/claude-code.json` for the server snippet.
   - If the user wants the server available only for one project, merge the snippet into that project's `mcpServers` key. Otherwise merge it into the top-level `mcpServers` key. Preserve any existing servers.
   - Write the merged result back to `~/.claude.json`.
   - Tell the user to open the MCP UI in Claude Code and click `Authorize` for the DoiT server.
   - Tell the user to restart Claude Code or run `/mcp` if the server does not appear immediately after saving.

### Cursor

Config file: `.cursor/mcp.json` in the project root.
Template: `templates/cursor.json`

1. Read `.cursor/mcp.json` (create it if it does not exist).
2. Read `templates/cursor.json` for the server snippet.
3. Merge the snippet into the existing `mcpServers` key (preserve any existing servers).
4. Write the merged result back to `.cursor/mcp.json`.
5. Tell the user to complete Cursor's OAuth flow for the DoiT server if Cursor prompts for authentication.
6. Tell the user to restart Cursor or reload the MCP servers panel if the server does not appear immediately after saving.

### Gemini CLI

Config file: `~/.gemini/settings.json`
Template: `templates/gemini-cli.json`

1. Read `~/.gemini/settings.json` (create it if it does not exist).
2. Read `templates/gemini-cli.json` for the server snippet.
3. Merge the snippet into the existing `mcpServers` key (preserve any existing servers).
4. Write the merged result back to `~/.gemini/settings.json`.
5. Tell the user to run `/mcp auth doit-mcp` in Gemini CLI if the server requires authentication.
6. Tell the user to restart Gemini CLI if the server does not appear immediately after saving.

### Codex

Config file: `~/.codex/config.toml`
Template: `templates/codex.toml`

1. Read `~/.codex/config.toml` (create it if it does not exist).
2. Read `templates/codex.toml` for the server snippet.
3. Merge the TOML snippet into the file, preserving any existing `mcp_servers` entries.
4. Write the merged result back to `~/.codex/config.toml`.
5. Tell the user they can alternatively run `codex mcp add doit-mcp --url https://mcp.doit.com/sse`.
6. Tell the user to restart Codex or run `codex mcp list` to verify the server is registered, then complete the authorization flow if prompted.

## Manual Clients

These clients require UI interaction the agent cannot automate. Guide the user step by step.

### ChatGPT

1. Tell the user to enable ChatGPT developer mode first.
2. Create a connector from `Settings` -> `Apps & Connectors` -> `Create`.
3. Set `MCP Server URL` to `https://mcp.doit.com/sse`.
4. Select `OAuth` for auth.
5. Tell the user they will need both the DoiT API key and DoiT Customer ID during authorization.

Do not give a local config snippet for ChatGPT.

### Claude (web)

1. Tell the user to add a custom connector in Claude.
2. Set the remote MCP server URL to `https://mcp.doit.com/sse`.
3. Tell the user to click `Authorize` in the Claude UI and complete the OAuth flow.

Do not mention Customer ID for Claude web.

## DCI CLI Installation

After configuring the MCP client, install the DoiT Cloud Intelligence CLI. The CLI provides direct terminal access to the same DoiT API that the MCP server uses.

### Installation

Detect the user's platform and run the appropriate install command:

- **macOS**: `brew install doitintl/dci-cli/dci`
- **Windows (WinGet)**: `winget install DoiT.dci`
- **Windows (Scoop)**: `scoop bucket add doitintl https://github.com/doitintl/dci-cli && scoop install dci`
- **Linux (.deb)**: Download from [Releases](https://github.com/doitintl/dci-cli/releases/latest) and `sudo dpkg -i dci_*_linux_amd64.deb`
- **Linux (.rpm)**: Download from [Releases](https://github.com/doitintl/dci-cli/releases/latest) and `sudo rpm -i dci_*_linux_amd64.rpm`

### Authentication

1. Run `dci login` directly. This opens a browser window for OAuth authentication via the DoiT Console.
2. Tell the user to complete the authorization in the browser that just opened.
3. After the user confirms they authorized, run `dci status` to verify the CLI is authenticated.
4. For CI/CD or non-interactive environments, the user can set `export DCI_API_KEY=<api-key>` instead of browser-based login.

### Quick Verification

After auth, run `dci list-reports` to confirm the CLI is working. If it returns a table of reports, the setup is complete.

## Verification

After setup, verify the connection:

1. For automated clients: confirm the DoiT MCP server appears in the client and is marked connected after authorization.
2. For manual clients: tell the user to confirm the DoiT MCP server shows as connected after authorization and the tool list is visible.
3. Suggest a smoke test prompt: "Show me recent anomalies" or "List my reports".

## Troubleshooting

For detailed troubleshooting, read `references/troubleshooting.md`.

Quick checks:

- If the user mixed local and remote setup patterns, correct the flow instead of trying to merge them.
- If auth fails in Claude, Claude Code, Codex, Cursor, or Gemini CLI, verify the user completed the remote authorization flow in the client.
- If auth fails in ChatGPT, check whether the wrong credential was used: API key plus Customer ID.
- If a config file already has a `doit-mcp`, `doit`, or `doit_mcp_server` entry, ask the user whether to overwrite or replace it with the remote connector format for that client.
- If the user asks for a client that is not covered here, say that supported clients are ChatGPT, Claude (web), Claude Code, Codex, Cursor, and Gemini CLI.

## Gotchas

- **Claude Code requires `"type": "sse"` and `"oauth": { "callbackPort": 8080 }`**: This is unique to Claude Code. Other clients infer the transport from the URL. Missing the `type` field or using `"type": "http"` causes a silent connection failure. The `oauth.callbackPort` is required for the OAuth callback to complete.
- **Cursor config is per-project**: The file lives at `.cursor/mcp.json` in the project root, not in the home directory. Setting it globally does not work.
- **Codex uses TOML, not JSON**: Writing JSON syntax into `~/.codex/config.toml` will break the file. Use the TOML template.
- **ChatGPT needs developer mode first**: Without enabling developer mode in Settings, the MCP connector option is not visible.
- **Do not mix local and remote**: If the user previously had a stdio-based setup (`command: "npx"`, `DOIT_API_KEY`), it must be fully removed before adding the remote HTTP setup. Mixing both causes duplicate or conflicting sessions.
- **OAuth tokens expire**: If a previously working connection stops, the most likely cause is an expired OAuth token. Re-authorize in the client UI.
- **`Billing Profiles Admin` is required**: Without this DoiT permission, tool calls will return 403 even if the connection succeeds. Verify this before starting setup.