Skip to main content
Glama
Brightdesk Connector

Brightdesk Connector

by memolabs-dev
README.md
# Brightdesk connector

A working MCP connector for Brightdesk, a made-up invoicing product. It shows how a SaaS can let its customers use the product from ChatGPT and Claude without leaking data or acting twice.

Live demo: `https://brightdesk.memolabs.dev/mcp`. All data is sample data held in memory, one fresh copy per connection. Restarting the server resets it.

## What it shows

| Tool | Kind | Guardrail enforced by the server |
|---|---|---|
| `list_overdue_invoices` | read only | Returns only invoices on the signed-in person's projects. |
| `agency_report` | read only | Refused unless the account is an admin. |
| `prepare_reminders` | read only | Builds a preview and a `draft_id`. Sends nothing. |
| `send_reminders` | action | Sends exactly the previewed draft, once, and only for the person who prepared it. |
| `record_payment` | action | A repeated `request_id` returns the first receipt and records nothing new. |

ChatGPT and Claude also ask before running an action, but a person can choose "Always allow". The tool annotations (`readOnlyHint` and the others) only change how the assistant presents a call. So every guardrail lives in the server.

## Sign-in

The server includes its own small OAuth 2.1 authorization server. It is built on the MCP TypeScript SDK's `OAuthServerProvider` interface, following the SDK's `demoInMemoryOAuthProvider` example. It provides:

- protected resource metadata at `/.well-known/oauth-protected-resource/mcp`;
- dynamic client registration at `/register` (Claude's "Register automatically" option);
- authorization code with PKCE, plus refresh tokens;
- tokens bound to the `/mcp` resource (RFC 8707);
- a sign-in page with two sample accounts: Lea, project manager, and Sam, agency admin.

## Run

```bash
npm install
npm test
PUBLIC_URL=https://your-public-host npm start
```

The server listens on `127.0.0.1:8787`. To connect it to Claude, it must be reachable over HTTPS at `PUBLIC_URL`, for example through a tunnel. Then go to Customize, Connectors, "+ Add", "Add custom connector", enter `PUBLIC_URL/mcp`, and choose "Register automatically" as the OAuth client.

## Limits

This is a demo, not a product:

- tokens and data live in memory;
- the sign-in page has no passwords;
- reminder emails are logged, not sent.

The tests in `test/` run the full sign-in and every guardrail through the official MCP client. `node test/live-check.mjs <url>` runs the same checks against a deployed server.

Built with `@modelcontextprotocol/sdk` 1.32.2, Express 5.3 and Zod 4.6.