Client Setup - Well Starter Kit

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

You can revoke access anytime from Well Dashboard > Settings > API Keys.

Claude Desktop

Available on Pro, Max, Team, and Enterprise plans.

Settings UI (OAuth)
Config File (API Key)

Open Settings

Open Claude Desktop → Settings → Connectors

Add Server

Click Add custom connector

Enter URL

https://api.wellapp.ai/v1/mcp

Authenticate

Click Add and log in with your Well account

Location:

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

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

Restart Claude Desktop after saving.

Claude Code

CLI - Remote (OAuth)
CLI - Local (API Key)
Config File (API Key)

# 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

claude mcp add well -- npx -y @wellapp/mcp \
  --env WELL_API_KEY="YOUR_API_KEY" \
  --env WELL_API_URL="https://api.wellapp.ai/v1"

Location: ~/.claude.json (user) or .mcp.json (project)

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

Useful commands:

claude mcp list          # List all MCP servers
claude mcp remove well   # Remove a server
claude mcp get well      # Get server info

Cursor

Open Settings

Click gear icon → Cursor Settings → Tools & Integrations

Open Config

Under MCP Tools, click Add Custom MCP → opens ~/.cursor/mcp.json

Add Configuration

Paste one of the configurations below and save

Remote (OAuth)
Local (API Key)

{
  "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.

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

Windsurf

Settings UI (OAuth)
Config File - Remote (OAuth)
Config File - Local (API Key)

Open Settings

Press Cmd + , (Mac) or Ctrl + , (Windows)

Navigate

Scroll to Cascade → MCP Servers

Add Server

Click Add Server → Add custom server

Configure

Enter name: well and URL: https://api.wellapp.ai/v1/mcp

Authenticate

Location:

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

{
  "mcpServers": {
    "well": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.wellapp.ai/v1/mcp"]
    }
  }
}

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

ChatGPT

Requires Pro or Plus plan with Developer Mode enabled.

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

Enable Developer Mode

Open ChatGPT → Settings → Advanced → Enable Developer mode

Add Connector

Go to Settings → Connectors → Add custom connector

Enter URL

https://api.wellapp.ai/v1/mcp

Authenticate

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:

Show me my invoices

What companies do I have in Well?

Find all unpaid invoices over 1000 EUR

Troubleshooting

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

OAuth redirect not working

Make sure you’re logged into Well 2. Clear browser cookies for wellapp.ai 3. Check your browser isn’t blocking popups

API Key not working

Verify the key is correct (no extra spaces) 2. Check the key hasn’t expired 3. Regenerate from Well Dashboard if needed

Connection lost / 401 errors

Remove the Well server from settings 2. Add it again 3. Re-authenticate

No data returned

Verify your Well workspace has data 2. Check you authorized the correct workspace

Logs location

Claude Desktop: - macOS: ~/Library/Logs/Claude/mcp*.log - Windows: %APPDATA%\Claude\logs\mcp*.log

​Permissions & Scopes

​ Claude Desktop

​ Claude Code

​ Cursor

​ Windsurf

​ ChatGPT

​Summary

​Test Your Connection

​Troubleshooting

​References

Permissions & Scopes

Claude Desktop

Claude Code

Cursor

Windsurf

ChatGPT

Summary

Test Your Connection

Troubleshooting

References