Connect an AI assistant

This article walks through connecting an AI coding assistant (Claude Code, GitHub Copilot, or OpenAI Codex) to your Casewhere instance through the MCP server. The quickest path is to Download the AI Workspace, which produces a ready-to-use project folder with the connection already configured.

sequenceDiagram
    participant U as You (Casewhere Admin)
    participant A as AI assistant
    participant M as MCP server
    participant C as Your Casewhere instance
    U->>U: Generate AI Access Token
    U->>A: Download AI Workspace (config files + token)
    A->>M: MCP request + headers (token, base URL)
    M->>C: Proxied Admin API call (as you)
    C-->>M: Result
    M-->>A: Tool result

Enable AI Integration (administrator)

AI Integration is off by default. An administrator enables it on the Casewhere Admin (configuration) site through two application settings:

App setting Value Effect
ai:EnableAI true Shows the AI Integration panel on the Admin home page and enables token endpoints
ai:McpBaseUrl The shared MCP server base URL, e.g. https://mcp-local.casewhere.com/ The URL the generated configuration points at (the /mcp endpoint is appended automatically)

These are standard application settings on the configuration web site (set in Web.config, or through your on-premise deployment settings). Until ai:McpBaseUrl is set, generated configs contain a <REPLACE_WITH_MCP_SERVER_URL> placeholder, and the MCP Base URL field shows "Not configured".

Generate an AI Access Token

The AI Integration panel on the Casewhere Admin home page

  1. Open Casewhere Admin and stay on the home page. When AI Integration is enabled you see the AI Integration panel.
  2. Click Generate Token. A new token is created and shown (masked) in the AI Access Token field.
  3. Click Copy Token if you want to paste it somewhere yourself. The token is a personal credential — treat it like a password.

The token is valid for 30 days and acts on your behalf with your permissions. To invalidate every token you have issued, click Revoke All AI Tokens.

Click Download AI Workspace to download casewhere-ai-workspace.zip. This generates a fresh token and packages it into a ready-made workspace:

File Used by Notes
.mcp.json Claude Code Picked up automatically when the folder is opened
.vscode/mcp.json GitHub Copilot Picked up automatically when the folder is opened in VS Code
.codex/config.toml OpenAI Codex MCP server entry for Codex
AGENTS.md and guide content All assistants Instructs the assistant to read the relevant Casewhere guide before creating or editing resources

Each config file is pre-filled with your token, this instance's base URL (X-Casewhere-BaseUrl), and the MCP server endpoint. Extract the zip anywhere and open the folder in your assistant.

Because the workspace embeds a live token, keep the extracted files private (do not commit them to a shared repository). When the token expires, click Download AI Workspace again and replace your config files.

Open the workspace in your assistant

Assistant What to do
Claude Code (CLI or VS Code extension) Open the workspace folder; Claude Code reads .mcp.json automatically. For an existing project, copy .mcp.json into your project root.
GitHub Copilot (VS Code) Open the workspace folder in VS Code (1.99+). The .vscode/mcp.json config is picked up automatically. Switch Copilot Chat to Agent mode to use MCP tools.
OpenAI Codex Copy the values from .codex/config.toml into Codex Settings → MCP Servers → Add server, or append them to your ~/.codex/config.toml (on Windows, C:\Users\<your-username>\.codex\config.toml) and restart Codex. Open the workspace folder so Codex picks up AGENTS.md.

Configure manually (alternative)

If you prefer not to use the AI Workspace, add the MCP server to your assistant by hand. Replace <MCP Base URL> with the value shown in the MCP Base URL field, <AI Access Token> with your generated token, and the base URL with your instance.

Claude Code — .mcp.json:

{
  "mcpServers": {
    "casewhere": {
      "type": "http",
      "url": "<MCP Base URL>/mcp",
      "headers": {
        "Authorization": "Bearer <AI Access Token>",
        "X-Casewhere-BaseUrl": "https://your-instance.casewhere.com/"
      }
    }
  }
}

GitHub Copilot — .vscode/mcp.json (note the root key is servers, not mcpServers):

{
  "servers": {
    "casewhere": {
      "type": "http",
      "url": "<MCP Base URL>/mcp",
      "headers": {
        "Authorization": "Bearer <AI Access Token>",
        "X-Casewhere-BaseUrl": "https://your-instance.casewhere.com/"
      }
    }
  }
}

OpenAI Codex — config.toml:

[mcp_servers.casewhere]
url = "<MCP Base URL>/mcp"
http_headers = { Authorization = "Bearer <AI Access Token>", X-Casewhere-BaseUrl = "https://your-instance.casewhere.com/" }

Verify the connection

Ask your assistant to ping Casewhere (this calls the PingCasewhere tool). It returns the targeted backend URL and whether the connection is healthy. A successful ping confirms the MCP server is reachable, the base URL is correct, and your token is valid.

Token lifetime and rotation

  • Expiry — tokens last 30 days. When a token expires, the assistant's calls stop being authorized. Generate a new token (or re-download the AI Workspace) and update your config.
  • Rotation / leaks — if a token is ever exposed, click Revoke All AI Tokens and generate a new one. Revocation is immediate and cannot be undone.
  • Identity — every action is performed as you. Review what an assistant proposes before letting it run changes against a shared environment.

Next: Working with MCP tools.