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

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

Claude Desktop

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

Add to Claude

Opens your Claude connector settings. Add https://api.wellapp.ai/v1/mcp and sign in.

1
Open Settings
Open Claude Desktop → Settings → Connectors
2
Add Server
Click Add custom connector
3
Enter URL
```
https://api.wellapp.ai/v1/mcp
```
4
Authenticate
Click Add and log in with your Well account

Claude Code

# 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

Useful commands:

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

Cursor

1
Open Settings
Click gear icon → Cursor Settings → Tools & Integrations
2
Open Config
Under MCP Tools, click Add Custom MCP → opens ~/.cursor/mcp.json
3
Add Configuration
Paste one of the configurations below and save

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

Windsurf

1
Open Settings
Press Cmd + , (Mac) or Ctrl + , (Windows)
2
Navigate
Scroll to Cascade → MCP Servers
3
Add Server
Click Add Server → Add custom server
4
Configure
Enter name: well and URL: https://api.wellapp.ai/v1/mcp
5
Authenticate
Log in with your Well account when prompted

ChatGPT

Requires Pro or Plus plan with Developer Mode enabled.

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

1
Enable Developer Mode
Open ChatGPT → Settings → Advanced → Enable Developer mode
2
Add Connector
Go to Settings → Connectors → Add custom connector
3
Enter URL
https://api.wellapp.ai/v1/mcp
4
Authenticate
Log in with your Well account

Codex

OpenAI Codex CLI. Codex supports remote MCP servers and OAuth natively — no mcp-remote bridge needed.

Add the server to ~/.codex/config.toml:

[mcp_servers.well]
url = "https://api.wellapp.ai/v1/mcp"

Then authenticate (opens a browser to sign in to Well):

codex mcp login well

Or add it in one command instead of editing the file:

codex mcp add well --url https://api.wellapp.ai/v1/mcp
codex mcp login well

Team setup: commit a project-scoped .codex/config.toml with the same [mcp_servers.well] block so collaborators on a trusted project get Well automatically (the Codex counterpart of a committed .mcp.json).

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	—
Codex	`codex mcp login` (native)	`config.toml`

Test Your Connection

Once configured, try these prompts:

Show me my invoices

Troubleshooting

Cursor: 'Protected resource does not match'

This error occurs with mcp-remote. Try:

Clear the mcp-remote cache:
- macOS/Linux: rm -rf ~/.mcp-auth
- Windows: rmdir /s /q "%USERPROFILE%\.mcp-auth"
Restart Cursor completely
Make sure you're using https://api.wellapp.ai/v1/mcp exactly

OAuth redirect not working

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

API Key not working

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

Connection lost / 401 errors

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

No data returned

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

Logs location

Claude Desktop:

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