# Lemon Domains MCP server

Remote Model Context Protocol (MCP) server for managing a domain portfolio. Connect an AI client and manage domains, projects, registrars, and registrar accounts in natural language.

## Connection

- Endpoint: https://mcp.lemon.domains/mcp
- Transport: Streamable HTTP (no SSE)
- Auth: Bearer token (header-capable clients) OR OAuth (connector clients)
- Docs: https://docs.lemon.domains
- It is a remote server, nothing to install. There is no npm package; connect by URL.

## Authentication

Bearer token: create a personal access token at https://lemon.domains/mcp and send `Authorization: Bearer <token>` (prefix `lemd_`) on every request. Tokens are full-access and revocable.
OAuth: connector clients (Claude.ai, Claude Desktop, ChatGPT) add the endpoint as a custom connector and sign in with the email on their Lemon Domains account. Protected-resource metadata is at https://mcp.lemon.domains/.well-known/oauth-protected-resource.

## Connect a client

### Claude Code (Anthropic's CLI): Bearer token
1. Generate a token on the MCP page in your Lemon Domains account.
2. Run the command below, replacing YOUR_TOKEN.
3. Run /mcp inside Claude Code to confirm it connected.

```bash
claude mcp add lemon-domains \
  --transport http \
  --header "Authorization: Bearer YOUR_TOKEN" \
  https://mcp.lemon.domains/mcp
```

### Cursor (AI code editor): Bearer token
1. Generate a token on the MCP page.
2. Add the block below to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global).
3. Reload Cursor; the lemon-domains tools appear in the MCP panel.

```json
{
  "mcpServers": {
    "lemon-domains": {
      "url": "https://mcp.lemon.domains/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}
```

### Claude.ai & Claude Desktop (Anthropic web + desktop app): OAuth
1. Settings → Connectors → Add custom connector.
2. Server URL: https://mcp.lemon.domains/mcp
3. Click Connect; sign in with the email on your Lemon Domains account and approve.

### ChatGPT (OpenAI (Developer mode / connectors)): OAuth
1. Enable connectors in ChatGPT Settings (Plus/Pro/Business/Enterprise).
2. Add a custom connector / MCP server.
3. Server URL: https://mcp.lemon.domains/mcp; authenticate via OAuth with your Lemon Domains email.

### Windsurf (AI code editor): Bearer token
1. Open the Cascade MCP settings.
2. Add a server with the config below.

```json
{
  "mcpServers": {
    "lemon-domains": {
      "serverUrl": "https://mcp.lemon.domains/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}
```

### Any MCP client (Generic / raw HTTP): Bearer token
1. Point the client at the server URL using the Streamable HTTP transport.
2. Send Authorization: Bearer YOUR_TOKEN on every request.
3. Probe with the curl below to list tools.

```bash
curl -X POST https://mcp.lemon.domains/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

## Tools (21)

All tools are scoped to the authenticated user and respect project roles. Kinds: read (no mutation), write (create/update), delete (irreversible).

### Domains
The core of the portfolio. Every domain belongs to a project and a registrar account.

- `list_domains` [read]: List domains in your portfolio, with optional filters.
  - `projectId` uuid optional (filter to one project)
  - `registrarAccountId` uuid optional (filter to one registrar account)
  - `status` "Active" | "Expired" | "Transferred" | "Unknown" optional
  - `search` string optional (case-insensitive substring match on the domain name)
  - `expiringWithinDays` integer optional (only domains expiring within N days)
  - `limit` integer optional default 100 (max 500)

- `get_domain` [read]: Fetch one domain by id or by exact domain name.
  - `id` uuid optional (provide id or domainName)
  - `domainName` string optional

- `add_domain` [write]: Add a domain to a project under a registrar account.
  - `domainName` string required
  - `projectId` uuid required
  - `registrarAccountId` uuid required
  - `status` "Active" | "Expired" | "Transferred" | "Unknown" optional default "Active"
  - `autoRenew` boolean optional default false
  - `expiryDate` string optional (YYYY-MM-DD)
  - `notes` string optional (max 2000 chars)

- `update_domain` [write]: Update fields on a domain. Only provided fields change.
  - `id` uuid required
  - `domainName` string optional
  - `status` "Active" | "Expired" | "Transferred" | "Unknown" optional
  - `autoRenew` boolean optional
  - `expiryDate` string optional (YYYY-MM-DD or null)
  - `notes` string optional
  - `projectId` uuid optional (move to another project)
  - `registrarAccountId` uuid optional

- `delete_domain` [delete]: Permanently delete a domain. Irreversible.
  - `id` uuid required

- `bulk_add_domains` [write]: Add up to 200 domains in one call. Returns added rows and per-row errors so a single bad entry never fails the batch.
  - `domains` object[] required (1 to 200 entries, each shaped like add_domain)

- `domains_expiring_soon` [read]: Domains expiring within N days, soonest first.
  - `withinDays` integer optional default 30 (max 3650)
  - `limit` integer optional default 100 (max 500)

### Projects
Organizational grouping for domains. Membership controls access.

- `list_projects` [read]: List projects you belong to, with your role and a domain count.

- `add_project` [write]: Create a project. You become its owner.
  - `name` string required (max 100 chars)
  - `description` string optional (max 500 chars)

- `update_project` [write]: Rename or re-describe a project. Requires edit access.
  - `id` uuid required
  - `name` string optional
  - `description` string optional

- `delete_project` [delete]: Delete a project and ALL of its domains. Owner only. Irreversible.
  - `id` uuid required

### Registrars
The registrar platforms you use (Namecheap, Porkbun, Cloudflare, …).

- `list_registrars` [read]: List your registrar platforms with account counts.

- `add_registrar` [write]: Add a registrar platform.
  - `name` string required
  - `url` string optional (e.g. namecheap.com)

- `update_registrar` [write]: Update a registrar's name or URL.
  - `id` uuid required
  - `name` string optional
  - `url` string optional

- `delete_registrar` [delete]: Delete a registrar. Cascades to its accounts and their domains. Irreversible.
  - `id` uuid required

### Registrar accounts
Individual logins at a registrar. One account can hold domains across many projects. API credentials cannot be set through MCP.

- `list_registrar_accounts` [read]: List your registrar accounts, optionally filtered.
  - `registrarId` uuid optional (filter by registrar)

- `add_registrar_account` [write]: Add an account under one of your registrars.
  - `registrarId` uuid required
  - `displayName` string required
  - `accountUsername` string required
  - `contactEmail` string optional
  - `domainListUrl` string optional

- `update_registrar_account` [write]: Update fields on a registrar account.
  - `id` uuid required
  - `displayName` string optional
  - `accountUsername` string optional
  - `contactEmail` string optional
  - `domainListUrl` string optional
  - `isActive` boolean optional

- `delete_registrar_account` [delete]: Delete a registrar account. Cascades to its domains. Irreversible.
  - `id` uuid required

### Sync (read-only)
Inspect the history of your monthly registrar sync rounds.

- `recent_sync_logs` [read]: Most recent sync logs across your registrar accounts.
  - `limit` integer optional default 20 (max 100)
  - `registrarAccountId` uuid optional

- `latest_sync_session` [read]: Your most recent monthly sync session and its per-account checklist.

## Limits
- Streamable HTTP only.
- bulk_add_domains: max 200 per call.
- Request timeout: 60s.
- Tokens are full read+write access; per-token scopes are planned.