accelo-mcp

A Model Context Protocol (MCP) server for Accelo. It exposes Accelo quote tools to MCP clients (such as LibreChat agents) and authenticates per user via Accelo OAuth, so every action respects that user's own Accelo permissions.

Status: early. Tools: list_quotes, get_quote, get_deal, create_quote, update_quote.

Use the read-only get_accelo_guide tool for firm-specific API quirks. Tools that accept filters support a structured filter parameter (preferred); the raw filters parameter remains available as an advanced escape hatch.

How auth works

This server is an OAuth proxy:

• To the MCP client it acts as an OAuth Authorization Server (with discovery + dynamic client registration + PKCE).

• To Accelo it acts as an OAuth client (authorization-code grant).

The MCP client never sees the Accelo token. Every authorization first shows a consent page on this service with the registered redirect origin and the client's registration age. The user must explicitly continue or deny; approval is required on every authorization by design, with no remembered-consent option. Continuing then redirects to Accelo's own consent screen. The resulting Accelo access/refresh tokens are stored locally (SQLite) keyed to an opaque subject, and the MCP client is handed one of our opaque tokens that maps back to it. Accelo tokens are refreshed automatically.

Related MCP server: AroFlo MCP

Quote fields

create_quote and update_quote model every client-editable Accelo quote field explicitly, each mapping 1:1 to an Accelo quote key. Pick the field that matches the user's intent — do not route client-facing body text into notes.

History: earlier versions only surfaced title and notes as named params; all other keys were reachable only through an unconstrained freeform fields map. A request to set the conclusion therefore got silently written to notes (Accelo accepts it, so no error was raised). These fields are now modeled explicitly and the freeform passthrough was removed. See src/mcp.js (editableQuoteFields).

Prerequisites

1. An Accelo deployment (e.g. https://YOURDEPLOY.api.accelo.com).

2. A registered Accelo Web Application (Accelo: Configurations -> API -> Register Application). Set its redirect URI to: https://<your-public-host>/oauth/callback

3. Node 20+ or Docker.

Configuration

Copy .env.example to .env and fill in:

Never commit .env (it is gitignored).

Run

Docker (recommended)

docker compose up -d --build
curl -s http://127.0.0.1:8788/healthz

The compose file publishes only on loopback (127.0.0.1:8788), mapping host port 8788 to container port 8787. Put a TLS reverse proxy (nginx, Caddy, etc.) in front of it for PUBLIC_BASE_URL.

Node

npm install
npm start

Deploying an update to the live host? Follow DEPLOY.md. The checkout at /opt/accelo-mcp is deploy:deploy-owned: you must run as the deploy user, update with git merge --ff-only origin/main, and run the pre/post-build symbol assertions. Container Up + /healthz ok do not prove the new code is actually in the image (see #29).

OAuth registry report

docker compose exec accelo-mcp node scripts/registry-report.mjs [--json] [--stale-days N]

The read-only report lists truncated client IDs, redirect origins, scope, creation and last-use times, live token counts, and distinct subject counts, followed by summary counts. It never outputs secrets, token values, or full redirect URIs. --json produces structured output; --stale-days defaults to 90.

• INERT: empty registered redirect list (takes precedence over other flags).

• STALE: no live refresh token and last use is unobserved or older than the threshold.

• LIVE: otherwise, including clients holding a live refresh token.

never observed means no use recorded since activity tracking was introduced; existing clients are not backfilled. Successful token issuance/rotation and authenticated MCP requests record activity, at most once per client per minute. The default report does not delete clients or revoke tokens.

docker compose exec accelo-mcp node scripts/registry-report.mjs --prune
docker compose exec accelo-mcp node scripts/registry-report.mjs --prune --confirm

--prune is a read-only dry run: it lists the eligible rows with the same redaction as the report, then the total. Only --prune --confirm authorizes irreversible deletion; --confirm without --prune is an error. Pruning deletes only client rows holding no access or refresh token records, with no observed last use and created more than 24 hours ago. Any token record, even an expired one, protects its client from deletion. The fixed 24-hour guard protects registrations still in progress; --stale-days does not affect eligibility. Pruning does not delete tokens or revoke anything at Accelo. Confirmed pruning prints the actual deleted count and the resulting summary. This is operator-only, never scheduled.

Run inside the container or as deploy: the database is mode 0600; do not widen its permissions.

Endpoints

Using with LibreChat

Add an MCP server pointing at https://<your-public-host>/mcp with OAuth enabled. LibreChat will discover the OAuth endpoints, register a client, and prompt each user to authorize Accelo on first use. On every authorization, the user must also explicitly approve the consent page showing the registered redirect origin and client registration age; this is expected behavior and is not a failure or a one-time consent.

Rate limits & retry

The Accelo API enforces per-deployment rate limits (HTTP 429). A retry/backoff wrapper for the Node.js API client is tracked in issue #38.

→ See the firm's Accelo API Guide for the canonical pattern (includes the X-RateLimit-Reset-aware Node.js snippet).

License

MIT