eSeller World MCP Server

A remote Model Context Protocol server that exposes the eSeller World backend REST API as read/write tools, so Claude can work directly with:

• Site content (/api/content)

• Schema fields (model definitions — via schema_describe / schema://models)

• SEO metadata (/api/seo)

• URL structures (/api/redirects)

• Other content — blogs, case studies, portfolios, guides, categories, authors, contacts

It is a thin wrapper over the existing Express API in eSellerWorld-Backend-main — no backend changes required. Transport is Streamable HTTP (stateless), suitable for remote/hosted Claude clients.

Authentication — two ways to connect

The /mcp endpoint accepts either:

1. OAuth 2.1 (for the claude.ai / Claude Desktop Connectors UI). The server is a self-contained OAuth provider: dynamic client registration, a password-gated consent screen, PKCE, access + refresh tokens. Discovery metadata is served at /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource. Set PUBLIC_URL (the HTTPS origin) and MCP_LOGIN_PASSWORD (the consent password).

2. Static bearer token (for the Claude Code CLI). Send Authorization: Bearer <MCP_AUTH_TOKEN> — no OAuth dance.

Related MCP server: mcp-wordpress

⚠️ Security model (read this)

The backend API has no authentication of its own. This MCP server is therefore the security boundary:

• Every request to POST /mcp must present a valid OAuth token or the static MCP_AUTH_TOKEN; anything else gets 401.

• The OAuth consent screen is gated by MCP_LOGIN_PASSWORD (falls back to MCP_AUTH_TOKEN).

• The server refuses to start if MCP_AUTH_TOKEN is unset.

• OAuth tokens are stored in memory — they reset on redeploy (Claude simply re-authorizes). Fine for a single instance; add a shared store if you run multiple replicas.

• Write tools (*_create, *_update, *_delete, content_update) mutate live production data and are annotated as destructive so the MCP host prompts before each call.

Note: the token protects this MCP entrypoint only. Anyone who knows the backend origin can still call it directly — consider adding auth to the backend too, and always deploy the MCP behind HTTPS.

Setup

cp .env.example .env      # then edit values
npm install
npm run dev               # tsx watch, or: npm run build && npm start

Environment variables (.env):

Endpoints

• POST /mcp — the MCP JSON-RPC endpoint (bearer-protected).

• GET /healthz — unauthenticated liveness probe.

Connecting a Claude client

claude.ai / Claude Desktop Connectors UI (OAuth): add a custom connector with URL https://<your-host>/mcp. Claude registers itself, opens the consent screen — enter MCP_LOGIN_PASSWORD — and you're connected. No header needed.

Claude Code CLI (static bearer):

Remote MCP config:

{
  "mcpServers": {
    "esellerworld": {
      "url": "https://<your-host>/mcp",
      "headers": { "Authorization": "Bearer <MCP_AUTH_TOKEN>" }
    }
  }
}

In Claude Code you can also add it from the CLI:

claude mcp add --transport http esellerworld https://<your-host>/mcp --header "Authorization: Bearer <MCP_AUTH_TOKEN>"

Smoke test with curl

# initialize (should return serverInfo)
curl -s -X POST http://localhost:8080/mcp \
  -H "Authorization: Bearer $MCP_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'

# without the token -> 401
curl -s -o /dev/null -w "%{http_code}\n" -X POST http://localhost:8080/mcp -d '{}'

Deploy

Any Node host works (Render, Railway, Fly.io, a VPS behind Nginx). A Dockerfile is included:

docker build -t esellerworld-mcp .
docker run -p 8080:8080 --env-file .env esellerworld-mcp

Terminate TLS at the platform/reverse proxy and point clients at https://<host>/mcp.

Tool catalogue

• Content: content_list, content_get, content_version, content_update, content_delete

• SEO: seo_list, seo_get_by_path, seo_get_by_id, seo_create, seo_update, seo_delete*

• Redirects: redirects_list, redirect_get, redirect_check, redirect_create, redirect_update, redirect_toggle, redirect_delete, redirects_bulk_delete*

• Blogs: blogs_list, blog_get_by_slug, blog_get_by_id, blog_create, blog_update, blog_delete*

• Categories / Authors: categories_list, category_get, category_create…; authors_list, author_get, author_create…

• Case studies / Portfolios: case_studies_list, case_study_get_by_slug/id, CRUD*; portfolios_list, portfolio_get, CRUD*

• Guides: guide_collections_*, guide_faqs_*, guide_contents_* (list/get + CRUD*)

• Contacts (PII): contacts_list, contact_get, contact_update_status*

• Schema: schema_describe + resource schema://models

* = write tool (mutates live data).