Sweet Assist MCP Server

Standalone MCP server exposing Sweet Assist transactions, contacts, envelopes and agent profiles to Claude, behind an OAuth 2.1 login + approve flow.

Running locally

npm install
node index.js                      # http://localhost:3000

Expose it over HTTPS (Claude will not accept an http:// connector URL):

ngrok http 3000                    # then set SERVER_URL to the https URL it prints

SERVER_URL in .env must match the public URL exactly. It is used to build the OAuth metadata, the authorize/token endpoints and the redirect targets. If it still says http://localhost:3000 while Claude reaches you over a tunnel, the login redirect breaks.

Then in Claude: Settings → Connectors → Add custom connector → paste https://<your-host>/mcp.

Related MCP server: Clio Manage MCP

The connector flow

Public client with PKCE S256 — there is no client secret. Authorization codes are single-use and expire in 60 seconds.

Before production

1. Move clients / codes / tokens out of memory (oauth/store.js). They are Maps today, so a restart invalidates every connector and each broker must re-approve. These need database tables.

2. Add token revocation. revokeToken() exists but nothing calls it. Removing the connector in Claude should kill the token server-side.

3. Rate-limit POST /oauth/login. There is no throttling on password attempts.

4. Tighten CORS. app.use(cors()) currently allows any origin.

5. Serve over real HTTPS, not a dev tunnel.

6. Set a refresh token flow — access tokens currently last 30 days with no refresh.

Tools

list_transactions, get_transaction, list_envelopes, list_contacts, list_agents, get_my_profile — all read-only, all scoped to the authenticated broker and the agents beneath them via getScopedUserIds().

Transaction status

txn_transactions.status is an int owned by the Laravel app (TxnConstant::TXN_STATUS). It is surfaced as a label via STATUS_LABEL in constants.js — keep the two in step:

status: 'all' (the default) excludes deleted. An unrecognised status returns an error listing the valid ones rather than silently falling back to everything.

Transaction phase — prefer this filter

What the product calls a phase is not one column. Each tab a broker sees is a combination of phase, status and for_closed. PHASE_TABS in constants.js mirrors the Laravel app's Livewire/Transaction/Mongos/txnTable.php pipeline — if those tabs change, this must change too:

Note the trap: "Submitted For Closing" is not a phase value. It is for_closed = 1 while phase stays 1 or 0. Filtering on phase alone silently returns the wrong rows.

expired (status 4) and deleted (status 5) have no tab of their own but are accepted as phase names. Omitting phase returns everything except deleted.

list_transactions no longer advertises a status parameter. Offering both was the bug: asked for "my active transactions" the model picked status: 'active', which is the raw column — and a transaction moved to Closing still has status = 1, so it kept appearing under active. A status argument from an older client is still accepted and routed through the same tab table, so both spellings now mean the Active tab.