weclapp-mcp-server

A small remote MCP server that lets Claude read (and, if you extend it, write) data in your weclapp tenant. Your weclapp API token stays on this server — Claude only ever talks to this server, never to weclapp directly.

Tools included out of the box:

• list_customers, get_customer
• list_invoices, get_invoice
• list_articles
• weclapp_generic_get — fallback for any other GET endpoint

1. Configure

cp .env.example .env

Edit .env:

• WECLAPP_BASE_URL — for your tenant this is https://ecog.weclapp.com/webapp/api/v1
• WECLAPP_API_TOKEN — the API key you generated in weclapp under Settings → API
• MCP_SHARED_SECRET — make up a long random string yourself (e.g. run openssl rand -hex 32). This stops strangers from calling your server. You'll paste this same value into Claude later.

2. Run it locally first (sanity check)

npm install
npm start

You should see:

weclapp-mcp-server listening on port 3000
MCP endpoint: http://localhost:3000/mcp

If you have curl, you can smoke-test it:

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer YOUR_MCP_SHARED_SECRET" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

You should get back JSON listing the tools above.

3. Deploy it somewhere reachable over HTTPS

Claude needs to reach this server over the public internet with HTTPS. Local localhost won't work for the real connector. Easiest options, roughly cheapest/simplest first:

• Railway / Render / Fly.io — connect your GitHub repo (or drag-and-drop this folder), set the three env vars in their dashboard, deploy. They give you an HTTPS URL automatically.
• A VPS you already have — run with npm start behind a reverse proxy (e.g. Caddy or nginx) that terminates HTTPS, or use a tool like cloudflared tunnel to get HTTPS without configuring certificates yourself.

Whichever you choose, set the same three environment variables (WECLAPP_BASE_URL, WECLAPP_API_TOKEN, MCP_SHARED_SECRET) in that platform's settings — don't commit your .env file anywhere public.

You'll end up with something like:

https://your-app-name.up.railway.app/mcp

4. Connect it in Claude

1. Go to Claude Settings → Connectors.
2. Choose Add custom connector.
3. Paste your server's URL, e.g. https://your-app-name.up.railway.app/mcp.
4. When it asks for auth, choose the option for a custom header / bearer token, and enter your MCP_SHARED_SECRET value.
5. Save, then enable the connector for a chat.

Claude will now see list_customers, get_invoice, etc. as tools it can call when relevant, e.g. "look up invoice 1234 in weclapp."

5. Extend it

To add more tools (sales orders, quotations, contacts, etc.), copy the pattern of list_customers in server.js — most weclapp list endpoints follow the same shape: /{resource} with page, pageSize, and <field>-eq / <field>-like query filters. weclapp's full API reference is at https://{your-tenant}.weclapp.com/webapp/api/help (auth required, browse it while logged in).

Security notes

• Never put WECLAPP_API_TOKEN or MCP_SHARED_SECRET in code you commit to a public repo. Use your hosting platform's environment variable settings.
• This server currently allows any GET via weclapp_generic_get, which is convenient for exploring but also means Claude could read any data your API token can read. Remove that tool if you want to restrict access to only the specific tools above.
• If you add tools that create/update/delete data (POST/PUT/DELETE), treat those as higher-risk: consider requiring explicit confirmation in your prompts, or splitting a separate "read-only" token from a "write" token if weclapp's permission model supports it.