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.

The connector flow

Step	Endpoint	What happens
1	POST /mcp (no token)	401 + WWW-Authenticate pointing at the metadata
2	GET /.well-known/oauth-protected-resource	names the authorization server
3	GET /.well-known/oauth-authorization-server	endpoint metadata
4	POST /register	Claude registers itself (RFC 7591). No human step.
5	GET /oauth/authorize	branded Sweet Assist login page
6	POST /oauth/login	verifies the broker's password against users
7	POST /oauth/approve	the consent screen; redirects back with a code
8	POST /oauth/token	code + PKCE verifier → access token
9	POST /mcp (with token)	brokerId comes from the token, never a default

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:

Int	Name
1	Active
2	Closed (archived in the DB)
3	Canceled
4	Expired
5	Deleted
6	Canceled, Closed — matches both the closed and canceled filters

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:

Tab	phase	status	for_closed
Active	1	1	0
Pending	0	1	0
Submitted For Closing	1 or 0	1	1
Closing	3	1	—
Closed	3	2	—
Canceled	—	3	—

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.