> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wellapp.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Client Setup

> Configure Well MCP in your AI client

## Permissions & Scopes

When you authorize Well MCP, you grant access to:

| Scope             | Description                    |
| ----------------- | ------------------------------ |
| `invoices:read`   | View invoices and related data |
| `companies:read`  | View company records           |
| `companies:write` | Create new companies           |
| `people:read`     | View contact information       |
| `people:write`    | Create new contacts            |
| `documents:read`  | View uploaded documents        |
| `connectors:read` | View connected integrations    |

<Info>You can revoke access anytime from [Well Dashboard > Settings > API Keys](https://app.wellapp.ai/settings/api-keys).</Info>

***

## <img src="https://mintcdn.com/well/l3CiLHSkw-C0yewW/images/logos/claude.png?fit=max&auto=format&n=l3CiLHSkw-C0yewW&q=85&s=8e8ea77c8ba123bc02ebd5f13122fdb3" width="20" style={{margin: 0, marginRight: "8px", display: "inline", verticalAlign: "middle"}} data-path="images/logos/claude.png" /> Claude Desktop

<Info>Available on Pro, Max, Team, and Enterprise plans.</Info>

<Tabs>
  <Tab title="Settings UI (OAuth)">
    <div style={{marginTop: "-12px"}}>
      <Steps>
        <Step title="Open Settings">
          Open **Claude Desktop** → **Settings** → **Connectors**
        </Step>

        <Step title="Add Server">
          Click **Add custom connector**
        </Step>

        <Step title="Enter URL">
          ```
          https://api.wellapp.ai/v1/mcp
          ```
        </Step>

        <Step title="Authenticate">
          Click **Add** and log in with your Well account
        </Step>
      </Steps>
    </div>
  </Tab>

  <Tab title="Config File (API Key)">
    **Location:**

    * macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
    * Windows: `%APPDATA%\Claude\claude_desktop_config.json`

    ```json theme={null}
    {
      "mcpServers": {
        "well": {
          "command": "npx",
          "args": ["-y", "@wellapp/mcp"],
          "env": {
            "WELL_API_KEY": "YOUR_API_KEY",
            "WELL_API_URL": "https://api.wellapp.ai/v1"
          }
        }
      }
    }
    ```

    <Warning>Restart Claude Desktop after saving.</Warning>
  </Tab>
</Tabs>

***

## <img src="https://mintcdn.com/well/l3CiLHSkw-C0yewW/images/logos/claude.png?fit=max&auto=format&n=l3CiLHSkw-C0yewW&q=85&s=8e8ea77c8ba123bc02ebd5f13122fdb3" width="20" style={{margin: 0, marginRight: "8px", display: "inline", verticalAlign: "middle"}} data-path="images/logos/claude.png" /> Claude Code

<Tabs>
  <Tab title="CLI - Remote (OAuth)">
    ```bash theme={null}
    # Add Well MCP server
    claude mcp add --transport http well https://api.wellapp.ai/v1/mcp

    # Authenticate (opens browser)
    /mcp
    ```

    **Scope options:**

    | Flag              | Description                    |
    | ----------------- | ------------------------------ |
    | `--scope local`   | Current project only (default) |
    | `--scope project` | Shared via `.mcp.json`         |
    | `--scope user`    | All your projects              |
  </Tab>

  <Tab title="CLI - Local (API Key)">
    ```bash theme={null}
    claude mcp add well -- npx -y @wellapp/mcp \
      --env WELL_API_KEY="YOUR_API_KEY" \
      --env WELL_API_URL="https://api.wellapp.ai/v1"
    ```
  </Tab>

  <Tab title="Config File (API Key)">
    **Location:** `~/.claude.json` (user) or `.mcp.json` (project)

    ```json theme={null}
    {
      "mcpServers": {
        "well": {
          "command": "npx",
          "args": ["-y", "@wellapp/mcp"],
          "env": {
            "WELL_API_KEY": "YOUR_API_KEY",
            "WELL_API_URL": "https://api.wellapp.ai/v1"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

**Useful commands:**

```bash theme={null}
claude mcp list          # List all MCP servers
claude mcp remove well   # Remove a server
claude mcp get well      # Get server info
```

***

## <img src="https://mintcdn.com/well/l3CiLHSkw-C0yewW/images/logos/cursor.png?fit=max&auto=format&n=l3CiLHSkw-C0yewW&q=85&s=7941b42be5ca804cc43ca2dcdd811198" width="20" style={{margin: 0, marginRight: "8px", display: "inline", verticalAlign: "middle"}} data-path="images/logos/cursor.png" /> Cursor

<Steps>
  <Step title="Open Settings">
    Click **gear icon** → **Cursor Settings** → **Tools & Integrations**
  </Step>

  <Step title="Open Config">
    Under **MCP Tools**, click **Add Custom MCP** → opens `~/.cursor/mcp.json`
  </Step>

  <Step title="Add Configuration">Paste one of the configurations below and save</Step>
</Steps>

<Tabs>
  <Tab title="Remote (OAuth)">
    ```json theme={null}
    {
      "mcpServers": {
        "well": {
          "command": "npx",
          "args": ["-y", "mcp-remote", "https://api.wellapp.ai/v1/mcp"]
        }
      }
    }
    ```

    After saving, a browser window will open to authenticate with your Well account.
  </Tab>

  <Tab title="Local (API Key)">
    ```json theme={null}
    {
      "mcpServers": {
        "well": {
          "command": "npx",
          "args": ["-y", "@wellapp/mcp"],
          "env": {
            "WELL_API_KEY": "YOUR_API_KEY",
            "WELL_API_URL": "https://api.wellapp.ai/v1"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

***

## <img src="https://mintcdn.com/well/l3CiLHSkw-C0yewW/images/logos/windsurf.png?fit=max&auto=format&n=l3CiLHSkw-C0yewW&q=85&s=7ae0e4e632f8ba33c3be697c816be3be" width="20" style={{margin: 0, marginRight: "8px", display: "inline", verticalAlign: "middle"}} data-path="images/logos/windsurf.png" /> Windsurf

<Tabs>
  <Tab title="Settings UI (OAuth)">
    <Steps>
      <Step title="Open Settings">
        Press `Cmd + ,` (Mac) or `Ctrl + ,` (Windows)
      </Step>

      <Step title="Navigate">
        Scroll to **Cascade** → **MCP Servers**
      </Step>

      <Step title="Add Server">
        Click **Add Server** → **Add custom server**
      </Step>

      <Step title="Configure">
        Enter name: `well` and URL: `https://api.wellapp.ai/v1/mcp`
      </Step>

      <Step title="Authenticate">
        Log in with your Well account when prompted
      </Step>
    </Steps>
  </Tab>

  <Tab title="Config File - Remote (OAuth)">
    **Location:**

    * macOS: `~/.codeium/windsurf/mcp_config.json`
    * Windows: `%USERPROFILE%\.codeium\windsurf\mcp_config.json`

    ```json theme={null}
    {
      "mcpServers": {
        "well": {
          "command": "npx",
          "args": ["-y", "mcp-remote", "https://api.wellapp.ai/v1/mcp"]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Config File - Local (API Key)">
    ```json theme={null}
    {
      "mcpServers": {
        "well": {
          "command": "npx",
          "args": ["-y", "@wellapp/mcp"],
          "env": {
            "WELL_API_KEY": "YOUR_API_KEY",
            "WELL_API_URL": "https://api.wellapp.ai/v1"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

***

## <img src="https://mintcdn.com/well/l3CiLHSkw-C0yewW/images/logos/openai.png?fit=max&auto=format&n=l3CiLHSkw-C0yewW&q=85&s=65a4627aa5ae575823dcdaefd18992e7" width="20" style={{margin: 0, marginRight: "8px", display: "inline", verticalAlign: "middle"}} data-path="images/logos/openai.png" /> ChatGPT

<Info>Requires Pro or Plus plan with Developer Mode enabled.</Info>

<Warning>ChatGPT only supports remote MCP servers (no local/stdio mode).</Warning>

<Steps>
  <Step title="Enable Developer Mode">
    Open **ChatGPT** → **Settings** → **Advanced** → Enable **Developer mode**
  </Step>

  <Step title="Add Connector">Go to **Settings** → **Connectors** → **Add custom connector**</Step>
  <Step title="Enter URL">`https://api.wellapp.ai/v1/mcp`</Step>
  <Step title="Authenticate">Log in with your Well account</Step>
</Steps>

***

## Summary

| Client         | OAuth                      | API Key            |
| -------------- | -------------------------- | ------------------ |
| Claude Desktop | Settings UI                | Config file        |
| Claude Code    | CLI                        | CLI or config file |
| Cursor         | Config file (`mcp-remote`) | Config file        |
| Windsurf       | Settings UI                | Config file        |
| ChatGPT        | Settings UI                | —                  |

***

## Test Your Connection

Once configured, try these prompts:

<CodeGroup>
  ```text Invoices theme={null}
  Show me my invoices
  ```

  ```text Companies theme={null}
  What companies do I have in Well?
  ```

  ```text Filters theme={null}
  Find all unpaid invoices over 1000 EUR
  ```
</CodeGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Cursor: 'Protected resource does not match'">
    This error occurs with `mcp-remote`. Try: 1. Clear mcp-remote cache: - macOS/Linux: `rm -rf     ~/.mcp-auth` - Windows: `rmdir /s /q "%USERPROFILE%\.mcp-auth"` 2. Restart Cursor completely 3.
    Make sure you're using `https://api.wellapp.ai/v1/mcp` exactly
  </Accordion>

  <Accordion title="OAuth redirect not working">
    1. Make sure you're logged into Well 2. Clear browser cookies for `wellapp.ai` 3. Check your
       browser isn't blocking popups
  </Accordion>

  <Accordion title="API Key not working">
    1. Verify the key is correct (no extra spaces) 2. Check the key hasn't expired 3. Regenerate
       from [Well Dashboard](https://app.wellapp.ai) if needed
  </Accordion>

  <Accordion title="Connection lost / 401 errors">
    1. Remove the Well server from settings 2. Add it again 3. Re-authenticate
  </Accordion>

  <Accordion title="No data returned">
    1. Verify your Well workspace has data 2. Check you authorized the correct workspace
  </Accordion>

  <Accordion title="Logs location">
    **Claude Desktop:** - macOS: `~/Library/Logs/Claude/mcp*.log` - Windows:
    `%APPDATA%\Claude\logs\mcp*.log`
  </Accordion>
</AccordionGroup>

***

## References

* [Claude Desktop - Custom Connectors](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp)
* [Claude Code - MCP Docs](https://docs.anthropic.com/en/docs/claude-code/mcp)
* [Cursor - MCP Documentation](https://docs.cursor.com/context/model-context-protocol)
* [Windsurf - MCP Documentation](https://docs.windsurf.com/windsurf/cascade/mcp)
* [OpenAI - MCP Documentation](https://platform.openai.com/docs/mcp)