Forem: Eugen

[Boost]

Eugen — Mon, 27 Apr 2026 12:15:52 +0000

Eugen

Apr 27

We Built a Chrome Extension With Clean Architecture. Here's Why It Was Worth the Extra Effort.

#chromeextension #saas #typescript #react

Comments

7 min read

We Built a Chrome Extension With Clean Architecture. Here's Why It Was Worth the Extra Effort.

Eugen — Mon, 27 Apr 2026 08:34:18 +0000

Most Chrome extension tutorials show you a popup with a counter. Click a button, increment a number, done. That's fine for learning the API.

But what if your extension needs OAuth with PKCE, multi-tenant team switching, content script injection into arbitrary web pages, offline detection, session refresh via background alarms, and role-based access control?

We built a Chrome extension for PaperLink - a document sharing and analytics platform. The extension lets you create secure share links for your documents and insert them directly into any text field on any page - Gmail compose, Slack message box, Google Docs, whatever you're typing in.

We used Clean Architecture for the whole thing. Here's what that looks like in practice, and why we'd do it again.

The stack

WXT (Vite-based extension framework) - handles manifest generation, HMR, multi-browser builds
React 19 with side panel UI
Tailwind CSS v4 for styling
Vitest for testing (50+ test files)
TypeScript 6 with strict mode

Why Clean Architecture for a browser extension?

Browser extensions are deceptive. They look small, but they run across 3 execution contexts (background service worker, side panel, content scripts), talk to external APIs over HTTP, store tokens in browser.storage, inject scripts into pages you don't control, and need to handle offline/expired/deactivated states gracefully.

If you put all of that in one file, you get something that works but can't be tested, can't be refactored, and breaks every time Chrome changes an API.

We split the extension into 4 layers:

extension/src/
  domain/          # Pure types, entities, no dependencies
  application/     # Use cases + port interfaces
  infrastructure/  # Chrome APIs, HTTP client, clipboard, storage
  presentation/    # React components + hooks
  entrypoints/     # WXT entry points (background.ts, sidepanel/App.tsx)

Domain: 7 files, zero dependencies

domain/
  entities/authSession.ts
  types/document.ts
  types/link.ts
  types/result.ts
  types/team.ts
  types/teamRole.ts
  types/apiErrors.ts

The domain layer has no imports from any other layer. No chrome.*, no React, no HTTP. Just TypeScript types and one entity class.

The AuthSession entity is the most interesting piece:

export class AuthSession {
  private constructor(
    private readonly accessToken: string,
    private readonly refreshToken: string,
    private readonly expiresAt: number,
    private readonly userId: string,
    private readonly activeTeamId: string,
  ) {}

  static create(params: {
    accessToken: string;
    refreshToken: string;
    expiresIn: number;
    userId: string;
    activeTeamId: string;
  }): AuthSession {
    return new AuthSession(
      params.accessToken,
      params.refreshToken,
      Date.now() + params.expiresIn * 1000,
      params.userId,
      params.activeTeamId,
    );
  }

  isExpired(): boolean {
    return Date.now() >= this.expiresAt;
  }

  requiresRefresh(): boolean {
    return Date.now() >= this.expiresAt - 60_000;
  }

  withActiveTeamId(teamId: string): AuthSession {
    return new AuthSession(
      this.accessToken,
      this.refreshToken,
      this.expiresAt,
      this.userId,
      teamId,
    );
  }

  toStorable(): StorableSession { /* ... */ }
  static fromStorable(data: StorableSession): AuthSession { /* ... */ }
}

The 60-second refresh buffer means the background worker can catch tokens before they expire. The withActiveTeamId method returns a new instance instead of mutating - immutability matters when the same session object flows through multiple async operations.

We also defined a tiny Result type that every use case returns:

export type Result<T, E extends string = string> =
  | { ok: true; value: T }
  | { ok: false; error: E }
  | { ok: false; error: 'cancelled' };

No exceptions crossing layer boundaries. Every failure is typed and explicit.

Application: 10 use cases, 6 ports

application/
  ports/
    iAuthClient.ts
    iBrowserTabs.ts
    iClipboard.ts
    iContentScriptInjector.ts
    iPaperLinkApi.ts
    iStorage.ts
  use-cases/
    copyLinkUseCase.ts
    createLinkUseCase.ts
    insertLinkUseCase.ts
    listDocumentsUseCase.ts
    listLinksUseCase.ts
    openInAppUseCase.ts
    refreshSessionUseCase.ts
    signInUseCase.ts
    signOutUseCase.ts
    switchTeamUseCase.ts

Ports are interfaces. Use cases depend on ports, never on concrete implementations. This is the core inversion.

Here's CreateLinkUseCase - the most complex one, because it orchestrates API call, clipboard copy, and optional content script insertion:

export class CreateLinkUseCase {
  constructor(
    private readonly api: IPaperLinkApi,
    private readonly clipboard: IClipboard,
    private readonly contentScriptInjector: IContentScriptInjector,
  ) {}

  async execute(params: CreateLinkParams): Promise<Result<CreateLinkResult, CreateLinkError>> {
    if (params.teamRole === TEAM_ROLE_MEMBER) {
      return error('member_not_allowed');
    }

    // ... build input from params ...

    let link;
    try {
      link = await this.api.createLink(params.accessToken, input);
    } catch (err: unknown) {
      if (err instanceof Error && err.message === API_ERROR_FORBIDDEN) {
        return error('document_not_found');
      }
      return error('create_failed');
    }

    try {
      await this.clipboard.writeText(link.url);
    } catch {
      return error('clipboard_failed');
    }

    let inserted = false;
    if (params.mode === 'copyAndInsert' && params.activeTabId != null) {
      try {
        const result = await this.contentScriptInjector.insertAtCursor(
          params.activeTabId, link.url
        );
        inserted = result.inserted;
      } catch { /* clipboard already has the URL as fallback */ }
    }

    return success({ url: link.url, inserted });
  }
}

Notice what's NOT in this use case: no chrome.scripting.executeScript, no navigator.clipboard, no fetch. It doesn't know those exist. It talks to three interfaces and returns a typed result.

When content script injection fails (restricted page, no focused field, Chrome blocking it), the URL is already on the clipboard. The user still gets their link.

Infrastructure: where Chrome lives

infrastructure/
  api/paperLinkApiClient.ts
  auth/chromeAuthAdapter.ts
  clipboard/navigatorClipboardAdapter.ts
  content-scripts/rangeInsertionAdapter.ts
  storage/chromeStorageAdapter.ts
  config/appConfig.ts
  i18n/i18nProvider.tsx

Each adapter implements one port. The ChromeAuthAdapter is the OAuth implementation with PKCE:

export class ChromeAuthAdapter implements IAuthClient {
  async signIn(): Promise<AuthSession> {
    const codeVerifier = generateCodeVerifier();
    const codeChallenge = await generatePkceChallenge(codeVerifier);
    const state = generateState();
    const redirectUri = `https://${browser.runtime.id}.chromiumapp.org/`;

    const authUrl = new URL(`${APP_BASE_URL}/en/auth/extension-login`);
    authUrl.searchParams.set('client_id', CLIENT_ID);
    authUrl.searchParams.set('redirect_uri', redirectUri);
    authUrl.searchParams.set('code_challenge', codeChallenge);
    authUrl.searchParams.set('code_challenge_method', 'S256');
    authUrl.searchParams.set('state', state);

    const responseUrl = await browser.identity.launchWebAuthFlow({
      url: authUrl.toString(),
      interactive: true,
    });

    // ... validate state, extract code ...

    const tokenResponse = await this.exchangeCode(code, codeVerifier, redirectUri);
    return AuthSession.create({ /* ... */ });
  }
}

PKCE in a browser extension isn't optional - extensions can't keep client secrets. The browser.identity.launchWebAuthFlow opens a Chrome-managed auth window, and the extension receives the authorization code via redirect URL.

The content script injector is the most unusual adapter. It uses browser.scripting.executeScript to run code inside the active tab:

export class RangeInsertionAdapter implements IContentScriptInjector {
  async insertAtCursor(tabId: number, text: string): Promise<InsertResult> {
    const results = await browser.scripting.executeScript({
      target: { tabId },
      func: insertTextAtCursor,
      args: [text],
    });

    const result = results[0];
    if (result?.result === true) {
      return { inserted: true };
    }
    return { inserted: false, reason: 'no_editable_focus' };
  }
}

The injected function handles three cases: <input>, <textarea>, and contenteditable elements. It uses setRangeText for form fields and the Selection API for rich text editors. This covers Gmail, Slack, Notion, Google Docs, and most web apps.

Background service worker: 38 lines

export default defineBackground(() => {
  const storage = new ChromeStorageAdapter();
  const authClient = new ChromeAuthAdapter();
  const refreshUseCase = new RefreshSessionUseCase(authClient, storage);

  void browser.sidePanel.setPanelBehavior({ openPanelOnActionClick: true });
  void browser.alarms.create(ALARM_NAME, { periodInMinutes: 10 });

  browser.alarms.onAlarm.addListener((alarm) => {
    if (alarm.name !== ALARM_NAME) { return; }
    void (async () => {
      const stored = await storage.get<StorableSession>(STORAGE_KEY_AUTH_SESSION);
      if (!stored) { return; }
      const session = AuthSession.fromStorable(stored);
      if (session.requiresRefresh()) {
        await refreshUseCase.execute();
      }
    })();
  });
});

Every 10 minutes, the alarm fires. If there's a stored session and it's within the 60-second refresh window, refresh it silently. The user never sees an expired token.

This is only 38 lines because all the logic lives in RefreshSessionUseCase. The background script is just wiring.

Architecture tests guard the layers

We wrote tests that fail if any layer imports from a forbidden layer:

const FORBIDDEN_DOMAIN = ['@/application', '@/infrastructure', '@/presentation'];

describe('Domain - no upward imports', () => {
  it.each(domainFiles)('%s has no forbidden imports', file => {
    const imports = readFileImports(file);
    for (const imp of imports) {
      for (const forbidden of FORBIDDEN_DOMAIN) {
        expect(imp.startsWith(forbidden)).toBe(false);
      }
    }
  });

  it.each(domainFiles)('%s has no chrome references', file => {
    const content = readFileContent(file);
    expect(content).not.toMatch(/\bchrome\./);
  });
});

The test parses actual import statements from source files and checks them against a forbidden list per layer. Domain can't import from application, infrastructure, or presentation. Application can't import from presentation or infrastructure adapters. Presentation can't import infrastructure adapters directly.

These tests catch violations at CI time, not during code review.

What we actually shipped

The Chrome extension has:

OAuth with PKCE and team selection (multi-tenant)
Document list with cursor-based pagination and search
Link creation with optional password and expiry
"Create & Copy" and "Create & Insert in Page" actions
View existing links per document with view counts
Role-based UI (Members see read-only view)
Offline detection with banner
Session auto-refresh via background alarms
Stale session recovery
i18n (multiple locales)
Accessibility (ARIA labels, screen reader announcements)

All of that in ~60 source files and ~50 test files.

The tradeoffs

More files. A flat extension would be maybe 10 files. We have 60. Every new feature touches 3-4 layers.

Composition root in App.tsx. WXT doesn't have a DI container, so all adapters are instantiated at the top of the entry point and passed down. It's explicit, it works, but it's verbose.

Infrastructure adapters vary in size. The clipboard adapter is 11 lines, storage is 24. The auth adapter is 168 lines because PKCE is inherently complex, and the API client is 194 lines because it maps every endpoint. But the real business logic still lives in use cases and domain - adapters are just plumbing. Every use case can be tested with fake implementations of the ports - no browser.* mocking needed.

Chrome Web Store review: approved in 24 hours

We submitted v1 as a minimal release to get through the review process quickly. The extension was live in the Chrome Web Store within 24 hours.

From the review logs, we could see a Google tester spent about 5 minutes on the platform - signed up, created a document, shared a link, tried the extension. That was enough. The permission justifications were clear because each Chrome API (storage, identity, scripting, activeTab, alarms) maps to exactly one infrastructure adapter with a single responsibility.

We didn't get a single rejection or follow-up question. For an extension requesting scripting and activeTab permissions - which Chrome reviews carefully - that's not typical.

We've already shipped v1.1.0 with improvements, and more updates are coming. If you try the current version and it feels rough around the edges - check back in a few days. We're iterating fast.

Screenshots for the Chrome Web Store listing

The CWS listing needs 1280x800 screenshots. We took actual screenshots of the extension in use and processed them with AI image generation - cropping the extension panel, placing it on a clean white background, and adding context. This gave us polished marketing screenshots without a designer.

Would we do it again?

Yes. Three reasons:

Testing. Every use case is tested against port interfaces, not Chrome API mocks. When Chrome changes their scripting API, we change one adapter. Tests don't move.
The "Insert in Page" feature. This required coordinating between the side panel (React), background worker (alarms), content scripts (DOM injection), and the API. Without clear boundaries, this would have been a debugging nightmare. With ports and use cases, each piece is isolated and testable.
The review process. Clean Architecture made CWS review trivial. Each permission maps to one adapter, each adapter implements one port, each port serves specific use cases. When a reviewer asks "why do you need scripting?", the answer is one file: RangeInsertionAdapter.ts, 58 lines, used by InsertLinkUseCase to paste share links into focused text fields. That's it.

AI Accounting: 45 Seconds in a Form vs 10 Seconds in a Chat

Eugen — Fri, 24 Apr 2026 14:40:39 +0000

We built 118 MCP tools for our SaaS. About 35 of them handle accounting: transactions, transfers, recurring rules, categories, currencies, financial accounts. We timed the same operations in our web forms and through Claude. The difference was larger than we expected - in both directions.

This isn't a "forms are dead" post. It's a timing comparison with code. Some operations are 4x faster in conversation. Some are still better in a form. The interesting part is figuring out which is which.

Operation 1: Recording a single expense

Form: ~45 seconds

Open the accounting page. Click "New Transaction." Select type: Expense. Type amount: 12.50. Type description: "Coffee beans." Click the category dropdown, scroll through 40+ categories, find "Food & Dining", expand it, pick "Groceries." Select account from another dropdown. Click Save.

Conversation: ~10 seconds

"12.50 coffee beans, groceries, wise"

Claude calls list-categories with search: "groceries" to find the deepest matching subcategory:

server.registerTool(
  'list-categories',
  {
    description: 'Search expense/income categories by keyword. ALWAYS use the search ' +
      'parameter to find the deepest matching subcategory (e.g. search "groceries" to ' +
      'find "Food & Dining > Groceries" at depth 2, not "Food & Dining" at depth 0). ' +
      'Each result includes depth (0=root, 1-3=subcategory) - prefer the deepest match.',
    inputSchema: z.object({
      type: z.enum(['INCOME', 'EXPENSE']).optional(),
      search: z.string().max(200).optional(),
      limit: z.coerce.number().int().min(1).max(50).optional(),
    }),
    annotations: { readOnlyHint: true },
  },
  // ...
);

Then it resolves "wise" to the correct financial account via list-accounts, and calls create-transaction:

server.registerTool(
  'create-transaction',
  {
    description: 'Record a financial transaction. ' +
      'Workflow: 1) Search category via list-categories with a keyword ' +
      '2) Confirm category + account with user 3) Create transaction.',
    inputSchema: z.object({
      type: z.enum(['INCOME', 'EXPENSE']),
      amount: coerceAmount(),
      description: z.string().max(200),
      accountId: z.string(),
      categoryId: z.string().optional(),
      date: coerceDateString().optional(),
    }),
    annotations: { destructiveHint: false, idempotentHint: false },
  },
  // ...
);

Before creating anything, Claude confirms: "Record $12.50 expense 'Coffee beans' in Food & Dining > Groceries from Wise USD?" You say yes. Done.

The time difference comes from category selection. In a form, you navigate a tree. In a conversation, you type a keyword and the AI searches for the deepest match. "Groceries" resolves to Food & Dining > Groceries (depth 2) without you knowing the tree structure.

Operation 2: A 6-item receipt

Form: ~4 minutes

Six separate transactions. Open form, fill fields, save. Repeat five more times. Each one requires the same category navigation, same account selection. Copy-paste the date six times.

Conversation: ~20 seconds

"Receipt from today: milk 3.20, bread 2.10, eggs 4.50, butter 3.80, cheese 6.90, yogurt 2.40 - all groceries, wise account"

Claude calls create-transactions - one batch operation:

server.registerTool(
  'create-transactions',
  {
    description: 'Batch create multiple transactions in a single call. ' +
      'Use for multi-item receipts. Always confirm the full list of items, ' +
      'total amount, category, and account with the user before calling.',
    inputSchema: z.object({
      accountId: z.string(),
      categoryId: z.string().optional(),
      date: coerceDateString().optional(),
      transactions: coerceJsonArray(
        z.object({
          type: z.enum(['INCOME', 'EXPENSE']),
          amount: coerceAmount(),
          description: z.string().max(200),
          categoryId: z.string().optional(),
          date: coerceDateString().optional(),
        })
      ).describe('JSON array of 1-50 transactions'),
    }),
    annotations: { destructiveHint: false, idempotentHint: false },
  },
  // ...
);

The accountId, categoryId, and date are shared across all items - you specify them once. Individual transactions can override the category or date if needed. Claude confirms: "6 items, total $22.90, all Groceries, Wise USD, today. Create?" One tool call instead of six form submissions.

The batch endpoint accepts up to 50 transactions. The AI sends them as a JSON array inside a single parameter - parsed and validated by our coerceJsonArray helper (covered in post 2).

This is where the time gap is largest. 4 minutes vs 20 seconds is a 12x difference. And it's not because the form is badly designed - it's because the form treats each transaction as a separate operation.

Operation 3: Transfer between accounts

Form: ~30 seconds

Open transfers page. Select source account. Select destination account. If currencies differ, manually check today's exchange rate. Enter amount. Calculate the destination amount yourself. Save.

Conversation: ~10 seconds

"Transfer $500 from Wise to Mono"

Claude chains three operations: calls get-exchange-rates to find the USD/UAH rate, calculates the destination amount, then calls create-transfer:

server.registerTool(
  'create-transfer',
  {
    description: 'Transfer money between two financial accounts. ' +
      'Auto-fetches exchange rate for cross-currency transfers. ' +
      'For loan payments: confirm source account, loan account, amount, and category.',
    inputSchema: z.object({
      fromAccountId: z.string(),
      toAccountId: z.string(),
      amount: coerceAmount(),
      description: z.string().max(200).optional(),
      date: coerceDateString().optional(),
    }),
    annotations: { destructiveHint: false, idempotentHint: false },
  },
  // ...
);

Claude confirms: "Transfer $500 from Wise USD to Mono UAH. Rate: 1 USD = 41.25 UAH. Destination: 20,625 UAH. Proceed?" The exchange rate lookup that takes you 15 seconds on Google takes Claude one tool call.

Operation 4: Setting up a recurring expense

Form: ~60 seconds

Navigate to recurring transactions. Click "New." Fill in all the same fields as a regular transaction, plus: frequency (monthly), day of month, start date, optional end date. Save. Wonder if it actually worked until the first one generates.

Conversation: ~15 seconds

"Every month on the 1st, record $50 expense 'Spotify Family' from Wise, subscriptions category"

Claude calls create-recurring-transaction:

server.registerTool(
  'create-recurring-transaction',
  {
    description: 'Schedule a recurring transaction template. ' +
      'Does NOT generate a transaction immediately - the daily cron handles generation.',
    inputSchema: z.object({
      type: z.enum(['INCOME', 'EXPENSE', 'TRANSFER']),
      amount: coerceAmount(),
      description: z.string().max(200),
      accountId: z.string(),
      categoryId: z.string().optional(),
      targetAccountId: z.string().optional()
        .describe('Required for TRANSFER type'),
      intervalUnit: z.enum(['DAY', 'WEEK', 'MONTH']),
      intervalValue: z.coerce.number().int().positive(),
      dayOfMonth: z.coerce.number().int().min(1).max(31).optional()
        .describe('Required when intervalUnit=MONTH'),
      startDate: coerceDateString(),
      endDate: coerceDateString().optional(),
    }),
    annotations: { destructiveHint: false, idempotentHint: false },
  },
  // ...
);

One detail worth noting: the tool description says "Does NOT generate a transaction immediately." This is important for user expectations. The recurring transaction is a template - a daily cron job generates the actual transactions. Claude relays this: "Created monthly recurring expense. First transaction will generate on the 1st."

You can also ask "What's my recurring forecast?" and Claude calls get-recurring-forecast to show projected expenses, income, and net for the next 30 days.

Operation 5: Financial overview

Form: ~90 seconds

Open dashboard. Read the summary cards. Click into category breakdown. Switch the period filter. Go back. Open a different report. Mentally combine the numbers.

Conversation: ~10 seconds

"How did this month go compared to last month?"

Claude calls get-dashboard-stats with period: "thisMonth", then again with period: "lastMonth", and summarizes:

"This month: $4,200 income, $3,100 expenses, $1,100 net profit. Last month: $3,800 income, $2,900 expenses, $900 net. Income up 10.5%, expenses up 6.9%, net profit up 22.2%."

Then you ask "Where did the extra spending go?" and Claude calls get-category-breakdown:

server.registerTool(
  'get-category-breakdown',
  {
    description: 'Category-level spending or income breakdown for a period.',
    inputSchema: z.object({
      type: z.enum(['INCOME', 'EXPENSE']),
      period: z.string().optional()
        .describe('thisMonth, lastMonth, last3Months, etc.'),
      dateFrom: coerceDateString().optional(),
      dateTo: coerceDateString().optional(),
      scope: z.enum(['ALL', 'COMPANY', 'PERSONAL']).optional(),
      displayCurrency: z.string().optional(),
    }),
    annotations: { readOnlyHint: true },
  },
  // ...
);

"Top 3 expense categories this month: Rent $1,200 (38.7%), Food & Dining $680 (21.9%), Software & Subscriptions $420 (13.5%). The increase came from Food & Dining - up $180 vs last month."

The dashboard shows the same data. But the dashboard requires you to navigate between views and connect the dots yourself. The conversation connects them for you.

The timing table

Operation	Form	Conversation	Speedup
Single expense	~45s	~10s	4.5x
6-item receipt	~4min	~20s	12x
Cross-currency transfer	~30s	~10s	3x
Recurring expense setup	~60s	~15s	4x
Financial overview + drill-down	~90s	~10s	9x
Edit a specific transaction field	~15s	~10s	1.5x
Bulk categorize 20 transactions	~10min	~2min	5x

The pattern: conversation wins on discovery (finding categories, accounts, rates) and batching (multiple items in one operation). The speedup is largest when the form requires repetitive navigation.

Where forms still win

Not everything is faster in a conversation.

Complex table editing. Rearranging 20 line items on an invoice - drag and drop, adjust quantities, reorder rows. A conversation would be "move item 3 above item 1, change quantity of item 5 to 3, delete item 7." By the time you've described the changes, you could have done it in the UI.

Visual layouts. Designing a document template, choosing colors, positioning logos. Visual tasks need a visual interface.

Browsing and comparing. Scrolling through a list of 50 transactions to spot patterns. Your eyes are faster than describing what you're looking for - unless you know the exact filter, in which case the conversation wins again.

Precision editing. Changing an amount from 12.50 to 12.55. In a form: click, backspace twice, type 55. In a conversation: "Change the amount of transaction X to 12.55." Similar time, but the form gives you a visual confirmation that the cursor is in the right field.

The rule of thumb: if the task is about data entry, conversation wins. If the task is about spatial manipulation or visual comparison, forms win.

The confirmation flow

Every write operation in our MCP server has a confirmation step built into the AI's workflow. This isn't a technical feature of MCP - it's a convention enforced through tool descriptions.

Look at our create-transaction description:

Workflow: 1) Search category via list-categories with a keyword
2) Confirm category + account with user
3) Create transaction
4) Show full details

And create-transfer:

For loan payments: confirm source account, loan account,
amount, and category.

And delete-transaction:

NEVER call without explicit user confirmation.
Always show full transaction details first.
Deletion is permanent and cannot be undone.

The AI reads these instructions and follows them. It doesn't call create-transaction immediately after you say "12.50 coffee beans." It first resolves the category, resolves the account, and asks "Record $12.50 expense 'Coffee beans' in Food & Dining > Groceries from Wise USD?" Only after you confirm does it execute.

This is different from a form's "Save" button. The form shows you what you're about to save, but you filled in every field yourself - typos are your problem. The conversation shows you what the AI understood, which catches misinterpretations before they become data.

We've seen cases where the AI catches ambiguity that a form can't: "You said 'wise' - you have two Wise accounts: Wise USD and Wise EUR. Which one?" A form dropdown shows both, but it doesn't know which one you usually use for groceries. The AI does, and asks only when it's uncertain.

How we enforce confirmation in tool descriptions

The convention is simple: destructive or write tools include explicit workflow instructions in their description field. The AI treats these as guidelines for its behavior.

Three levels:

Suggest workflow: "Search category first, confirm with user, then create." The AI usually follows this but might skip if the context is clear.

Strong warning: "NEVER call without explicit user confirmation. Show current values and proposed changes first." The AI almost always asks before proceeding.

Hard constraint: "Deletion is permanent and cannot be undone." Combined with annotations: { destructiveHint: true }, some MCP clients will add their own confirmation dialog on top of the AI's confirmation.

This isn't bulletproof - the AI can still make mistakes. But the combination of tool descriptions, annotations, and the AI's natural tendency to confirm ambiguous operations catches most errors before they happen.

Multi-currency: the hidden complexity

PaperLink supports multiple currencies per team. This adds complexity that conversations handle better than forms.

In a form: you pick a source account (Wise USD), pick a destination account (Mono UAH), then manually look up the exchange rate, calculate the destination amount, and enter it. If the rate changes between your Google search and clicking Save, you're off by a few cents.

In a conversation: "Transfer $500 from Wise to Mono." The AI calls get-exchange-rates, gets the current rate, calculates automatically, and shows you the result for confirmation. If you have a manual rate override (set via set-manual-exchange-rate for internal transfers at a fixed rate), it uses that instead.

The currency tools also handle setup:

> "Add British pounds to our currencies"

Claude calls add-team-currency with currencyCode: "GBP".
Auto-fetches the exchange rate. Done.

> "What are our current rates?"

Claude calls list-team-currencies.
"USD (base), EUR (0.92), UAH (41.25), GBP (0.79). All rates auto-updated."

> "Set EUR rate to 0.95 for this month's invoices"

Claude calls set-manual-exchange-rate with base: "USD", target: "EUR", rate: 0.95.
"Manual rate set: 1 USD = 0.95 EUR. This overrides the auto rate until you remove it."

The one-liner

claude mcp add --transport http paperlink https://mcp.paperlink.online/api/mcp/mcp

Connect, grant accounting:read and accounting:write scopes, and try: "What did I spend on groceries last month?"

MCP Auth That Actually Works: OAuth for Remote Servers

Eugen — Fri, 24 Apr 2026 14:22:51 +0000

In the first post I showed what an AI does with 118 MCP tools. In the second I showed how we organized them. Both posts assumed a working connection. This one covers the hardest part: getting that connection to work securely.

Most MCP servers run locally. You add a JSON block to your Claude config, paste an API key, and you're done. That works for developer tools. It doesn't work for a SaaS product where users have teams, roles, and data they share with other people.

We needed something different: a remote MCP server where users log in through their browser, pick a team, choose what the AI can access, and revoke it whenever they want. No API keys. No config files on disk.

The problem with local MCP servers

The standard MCP setup looks like this:

{
  "mcpServers": {
    "my-tool": {
      "command": "npx",
      "args": ["my-mcp-server"],
      "env": {
        "API_KEY": "sk-live-abc123"
      }
    }
  }
}

This has three problems for a SaaS product:

1. API keys are static secrets. If a key leaks, it has full access until someone manually rotates it. There's no expiry, no scope, no revocation without generating a new key.

2. No user consent flow. The user pastes a key and hopes for the best. There's no screen that says "this AI assistant wants to read your invoices and create transactions - approve?"

3. No multi-tenancy. If your product has teams, which team does the API key belong to? If a user is on three teams, do they need three keys? How do they switch?

A remote MCP server with OAuth solves all three. The user authenticates through a browser, picks a team, grants specific permissions, and gets a token that expires in an hour. The AI never sees a password. The user can disconnect from the app's settings page.

What we built

Our MCP server runs at https://mcp.paperlink.online/api/mcp/mcp and uses streamable HTTP transport - no local process, no stdio, no binary to install. The connection command is:

claude mcp add --transport http paperlink https://mcp.paperlink.online/api/mcp/mcp

When a client connects for the first time, it discovers the OAuth endpoints through two well-known documents. Then it runs a standard OAuth 2.1 authorization code flow with PKCE. The user sees a consent screen in their browser. After approval, the client gets a short-lived access token and a 30-day refresh token.

Here's the full flow:

Client                         Server                         User's Browser
  |                              |                                  |
  |-- GET /.well-known/          |                                  |
  |   oauth-protected-resource ->|                                  |
  |<- {auth_server, scopes}      |                                  |
  |                              |                                  |
  |-- GET /.well-known/          |                                  |
  |   oauth-authorization-server |                                  |
  |<- {authorize, token, revoke} |                                  |
  |                              |                                  |
  |-- Open browser: /authorize?  |                                  |
  |   code_challenge=...&        |                                  |
  |   scope=invoices:read ------>|-- Redirect to consent UI ------->|
  |                              |                                  |
  |                              |          User picks team,        |
  |                              |          reviews scopes,         |
  |                              |          clicks Approve          |
  |                              |                                  |
  |                              |<- POST consent (teamId, scopes) -|
  |<- Redirect: ?code=abc123    -|                                  |
  |                              |                                  |
  |-- POST /token               -|                                  |
  |   code=abc123&               |                                  |
  |   code_verifier=xyz          |                                  |
  |<- {access_token, refresh}    |                                  |
  |                              |                                  |
  |-- POST /api/mcp/mcp         -|                                  |
  |   Authorization: Bearer ...  |                                  |
  |<- Tool results               |                                  |

Let me walk through each piece.

Step 1: Discovery

MCP clients discover auth endpoints through two standard documents. The protected resource metadata tells the client where to authenticate:

GET https://mcp.paperlink.online/.well-known/oauth-protected-resource

{
  "resource": "https://mcp.paperlink.online/api/mcp/mcp",
  "authorization_servers": ["https://app.paperlink.online"],
  "scopes_supported": [
    "invoices:read", "accounting:read", "accounting:write", "accounting:delete",
    "companies:read", "companies:write", "clients:read", "clients:write",
    "products:read", "products:write", "companies:delete", "clients:delete",
    "products:delete", "invoices:write", "invoices:delete",
    "estimates:read", "estimates:write", "estimates:delete",
    "teams:read", "teams:write", "billing:read",
    "ai:read", "ai:write", "sharing:read", "sharing:write"
  ]
}

Then the authorization server metadata tells the client the exact endpoints:

GET https://app.paperlink.online/.well-known/oauth-authorization-server

{
  "issuer": "https://app.paperlink.online",
  "authorization_endpoint": "https://app.paperlink.online/api/oauth/authorize",
  "token_endpoint": "https://app.paperlink.online/api/oauth/token",
  "revocation_endpoint": "https://app.paperlink.online/api/oauth/revoke",
  "registration_endpoint": "https://app.paperlink.online/api/oauth/register",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "token_endpoint_auth_methods_supported": ["none"],
  "code_challenge_methods_supported": ["S256"],
  "scopes_supported": ["invoices:read", "..."]
}

Notice code_challenge_methods_supported: ["S256"]. We only support S256, not plain. This is intentional - plain PKCE offers almost no security benefit over no PKCE at all.

Also notice token_endpoint_auth_methods_supported: ["none"]. MCP clients are public clients (no client secret), so authentication happens entirely through PKCE.

Step 2: Authorization

The client opens the user's browser to the authorization endpoint:

GET /api/oauth/authorize?
  response_type=code&
  client_id=claude-desktop&
  redirect_uri=http://localhost:5555/callback&
  code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&
  code_challenge_method=S256&
  scope=invoices:read+accounting:write+sharing:read&
  state=random-csrf-token

The server validates the request and redirects to the consent UI. Two things get validated before the user sees anything:

// Only S256 - reject plain PKCE
if (codeChallengeMethod !== 'S256') {
  return NextResponse.json({
    error: 'invalid_request',
    error_description: 'Only code_challenge_method=S256 is supported',
  }, { status: 400 });
}

// Redirect URI must match known patterns
if (!isAllowedRedirectUri(clientId, redirectUri)) {
  return NextResponse.json({
    error: 'invalid_request',
    error_description: 'redirect_uri is not registered for this client',
  }, { status: 400 });
}

The redirect URI validation is worth expanding on. MCP clients use localhost callbacks (Claude Desktop uses http://localhost:PORT/callback), and browser-based clients like Claude.ai and ChatGPT use their own domains. We maintain an allowlist:

const SAFE_REDIRECT_PATTERNS = [
  'http://127.0.0.1:*/*',        // Desktop clients (IP)
  'http://localhost:*/*',         // Desktop clients (hostname)
  'https://*.claude.ai/*',       // Claude.ai
  'https://claude.ai/*',
  'https://*.chatgpt.com/*',     // ChatGPT
  'https://chatgpt.com/*',
  'https://*.openai.com/*',      // OpenAI
  'https://*.perplexity.ai/*',   // Perplexity
  'https://*.mistral.ai/*',      // Mistral
  'https://*.vscode.dev/*',      // VS Code
  // ... full list in mcpClientRegistry.ts
];

The patterns use glob-like matching: * in a port position matches any port, *.claude.ai matches any subdomain. The matcher parses the URI and compares scheme, host, port, and path separately.

Any client_id gets through as long as the redirect URI matches a known pattern. This is dynamic client registration - we don't pre-register clients. Security comes from PKCE plus redirect URI validation, not from client secrets.

Step 3: The consent screen

The consent screen is a regular Next.js page. The user must already be logged in (NextAuth session required). They see two things: a team picker and a scope list.

export function OAuthConsentForm({
  teams,
  requestedScopes,
  clientId,
  redirectUri,
  state,
  codeChallenge,
  codeChallengeMethod,
  dict,
}: OAuthConsentFormProps) {
  const [selectedTeamId, setSelectedTeamId] = useState<string | undefined>(
    teams[0]?.id
  );

  return (
    <form action={formAction}>
      {/* Team selector - one connection = one team */}
      <Dropdown
        options={teams.map(t => ({ value: t.id, label: t.name }))}
        value={selectedTeamId}
        onChange={setSelectedTeamId}
        label={dict.consent.selectTeam}
      />

      {/* Scope display - user sees what they're granting */}
      <ul>
        {requestedScopes.map(scope => (
          <li key={scope}>
            <span className="text-success">✓</span>
            {dict.consent.scopes[scope] ?? scope}
          </li>
        ))}
      </ul>

      <button type="button" onClick={handleDeny}>Deny</button>
      <button type="submit">Approve</button>
    </form>
  );
}

The team picker is the key piece. PaperLink is multi-tenant - a user might belong to "My Freelance Business" and "Acme Corp." Each MCP connection is scoped to exactly one team. If you want AI access to both teams, you create two connections. This is intentional: you might want Claude to have full access to your personal team but read-only access to the company team.

The scopes are displayed with human-readable labels from the i18n dictionary. invoices:read shows as "View invoices and estimates." accounting:write shows as "Create and modify transactions." Users understand what they're granting.

Step 4: Authorization code

When the user clicks Approve, a server action creates an authorization code:

async execute(input: CreateAuthorizationCodeInput): Promise<Result<{ code: string }>> {
  // Verify user is an active member of the selected team
  const member = await this.teamMemberRepository.findByTeamAndUser(
    input.teamId,
    input.userId
  );
  if (!member?.isActive()) {
    return Result.Forbidden(McpPermissionErrors.teamAccessDenied);
  }

  // 256-bit code (two UUIDs concatenated)
  const code = crypto.randomUUID() + crypto.randomUUID();

  // Only valid scopes pass through - invalid ones are silently dropped
  const validScopes = input.scopes.filter((s): s is McpScope =>
    Object.values(McpScope).includes(s as McpScope)
  );

  const entity = McpAuthorizationCodeEntity.create({
    code,
    userId: input.userId,
    teamId: input.teamId,
    teamRole: member.getRole(),   // OWNER, ADMIN, MANAGER, MEMBER
    codeChallenge: input.codeChallenge,
    codeChallengeMethod: input.codeChallengeMethod,
    scopes: validScopes,
    // expiresAt: now + 10 minutes (set automatically)
  });

  await this.mcpAuthorizationCodeRepository.save(entity);

  return Result.Success({ code });
}

The authorization code is a domain entity, not a raw database record. McpAuthorizationCodeEntity.create() validates all inputs and sets the 10-minute expiry automatically. The PKCE challenge is stored alongside the code for verification in the next step.

Two security details worth noting:

Invalid scopes are silently dropped, not rejected. If a client requests invoices:read admin:superpower, the code is created with only invoices:read. This prevents a misbehaving client from blocking the entire flow over an unrecognized scope.

Team membership is verified at code creation time, not just at consent display. A race condition where a user is removed from a team between seeing the consent screen and clicking Approve is handled here.

Step 5: Token exchange

The client exchanges the authorization code for tokens:

POST /api/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=<256-bit-code>&
code_verifier=<PKCE-verifier>&
redirect_uri=http://localhost:5555/callback&
client_id=claude-desktop

The exchange use case performs five validations:

async execute(input: ExchangeCodeForTokenInput): Promise<Result<TokenResponse>> {
  // 1. Find and DELETE the code in one operation (one-time use)
  const authCode = await this.mcpAuthorizationCodeRepository
    .findByCodeAndDelete(input.code);
  if (!authCode) return Result.Error('invalid_grant');

  // 2. Check the 10-minute window
  if (authCode.isExpired()) return Result.Error('invalid_grant');

  // 3. PKCE verification (timing-safe comparison)
  const pkceValid = await authCode.verifyCodeChallenge(input.codeVerifier);
  if (!pkceValid) return Result.Error('invalid_grant');

  // 4. Redirect URI must match exactly
  if (authCode.getRedirectUri() !== input.redirectUri) {
    return Result.Error('invalid_grant');
  }

  // 5. Client ID must match
  if (authCode.getClientId() !== input.clientId) {
    return Result.Error('invalid_grant');
  }

  // All checks passed - generate tokens
  const accessToken = generateSecureToken();   // 256-bit random
  const refreshToken = generateSecureToken();

  // Hash before storing - raw tokens never touch the database
  const [tokenHash, refreshTokenHash] = await Promise.all([
    sha256Hash(accessToken),
    sha256Hash(refreshToken),
  ]);

  const now = Date.now();
  const tokenEntity = McpAccessTokenEntity.create({
    userId: authCode.getUserId(),
    teamId: authCode.getTeamId(),
    teamRole: authCode.getTeamRole(),
    tokenHash,
    refreshTokenHash,
    scopes: authCode.getScopes(),
    clientName: authCode.getClientId(),
    expiresAt: new Date(now + ACCESS_TOKEN_TTL_MS),         // 1 hour
    refreshExpiresAt: new Date(now + REFRESH_TOKEN_TTL_MS), // 30 days
  });

  await this.mcpAccessTokenRepository.save(tokenEntity);

  return Result.Success({
    accessToken,       // Raw value - only time it exists
    refreshToken,
    expiresIn: ACCESS_TOKEN_EXPIRES_IN_SECONDS,
    tokenType: 'Bearer',
  });
}

The route handler converts camelCase to the OAuth-standard snake_case response:

const token = result.value!;
return NextResponse.json({
  access_token: token.accessToken,
  token_type: token.tokenType,
  expires_in: token.expiresIn,
  refresh_token: token.refreshToken,
});

The critical security choice here: tokens are hashed before storage. The database holds SHA-256(token), never the raw token. If someone dumps the database, they get hashes that can't be reversed into working tokens. The raw token is returned to the client exactly once and never stored on the server side.

This is the same pattern GitHub uses for personal access tokens. It's more secure than JWTs for this use case because tokens can be individually revoked without maintaining a blocklist. Find the hash in the database, delete it, done.

Step 6: Token verification on every request

Every MCP request hits the verification flow:

async function handleMcpRequest(request: Request): Promise<Response> {
  const authInfo = await verifyBearerToken(request);

  if (!authInfo) {
    return withMcpCors(
      new Response(
        JSON.stringify({
          error: 'invalid_token',
          error_description: 'No authorization provided',
        }),
        {
          status: 401,
          headers: {
            'Content-Type': 'application/json',
            'WWW-Authenticate':
              'Bearer resource_metadata="https://mcp.paperlink.online/.well-known/oauth-protected-resource"',
          },
        }
      )
    );
  }

  const server = createMcpServer(authInfo);
  const transport = new WebStandardStreamableHTTPServerTransport({});
  await server.connect(transport);
  return withMcpCors(await transport.handleRequest(request));
}

The verifyBearerToken function does three checks:

async execute(bearerToken: string): Promise<McpAuthInfoDto | null> {
  // 1. Hash the incoming token and look it up
  const tokenHash = await sha256Hash(bearerToken);
  const token = await this.mcpAccessTokenRepository.findByTokenHash(tokenHash);
  if (!token) return null;

  // 2. Check expiry and revocation
  if (token.isExpired() || token.isRevoked()) return null;

  // 3. Live membership check - is user still active in this team?
  const member = await this.teamMemberRepository.findByTeamAndUser(
    token.getTeamId(),
    token.getUserId()
  );
  if (!member?.isActive()) return null;

  return {
    userId: token.getUserId(),
    teamId: token.getTeamId(),
    teamRole: member.getRole(),
    scopes: token.getScopes(),
  };
}

Check #3 is the one most OAuth implementations skip. If a team admin removes a user, their MCP token should stop working immediately - not in an hour when the token expires. We check team membership on every request. It's one extra database query, and it means "remove from team" actually removes access.

The returned McpAuthInfoDto is a lightweight object that flows into every tool handler:

interface McpAuthInfoDto {
  userId: string;
  teamId: string;
  teamRole: string;      // OWNER, ADMIN, MANAGER, MEMBER
  scopes: McpScope[];    // [McpScope.INVOICES_READ, McpScope.ACCOUNTING_WRITE]
}

No password, no token, no hash - just the identity and permissions the tool needs.

Step 7: Scope enforcement in tools

Every tool checks its required scope before executing:

export const registerAccountingReadTools: ToolRegistrar = (server, authInfo) => {
  server.registerTool(
    'list-invoices',
    {
      title: 'List Invoices',
      description: 'List invoices for the authenticated team.',
      inputSchema: z.object({
        status: z.string().optional(),
        clientName: z.string().optional(),
        limit: z.coerce.number().int().min(1).max(100).optional(),
        offset: z.coerce.number().int().min(0).optional(),
      }),
      annotations: { readOnlyHint: true },
    },
    async (params) => {
      if (!authInfo.scopes.includes('invoices:read')) {
        return {
          content: [{ type: 'text', text: 'Insufficient scope - invoices:read required.' }],
          isError: true,
        };
      }

      const useCase = mcpUseCases.getListInvoicesViaMcpUseCase();
      const result = await useCase.execute({
        teamId: authInfo.teamId,  // Always from auth, never from params
        status: params.status,
        clientName: params.clientName,
        limit: params.limit,
        offset: params.offset,
      });

      if (!result.isSuccess) {
        return {
          content: [{ type: 'text', text: result.errors.join(', ') }],
          isError: true,
        };
      }

      return {
        content: [
          { type: 'text', text: `Found ${result.value.length} invoices.` },
          { type: 'text', text: JSON.stringify(result.value, null, 2) },
        ],
      };
    }
  );
};

Two things never come from the AI's parameters: teamId and userId. They always come from authInfo, which is populated from the verified token. Even if the AI sends teamId: "someone-elses-team" in the tool call, it's ignored. The auth context wins.

This is the same principle as "don't trust the client" in web apps, applied to AI clients. The AI is a client. It sends parameters. You validate them, but identity always comes from the token.

Token refresh

Access tokens expire in one hour. The client refreshes without user interaction:

async execute(input: { refreshToken: string }): Promise<Result<TokenResponse>> {
  const refreshTokenHash = await sha256Hash(input.refreshToken);
  const existingToken =
    await this.mcpAccessTokenRepository.findByRefreshTokenHash(refreshTokenHash);

  if (!existingToken) return Result.Error('invalid_grant');

  if (existingToken.isRefreshExpired() || existingToken.isRevoked()) {
    return Result.Error('invalid_grant');
  }

  // Issue new pair with same scopes
  const newAccessToken = generateSecureToken();
  const newRefreshToken = generateSecureToken();

  const [newTokenHash, newRefreshTokenHash] = await Promise.all([
    sha256Hash(newAccessToken),
    sha256Hash(newRefreshToken),
  ]);

  const now = Date.now();
  const newTokenEntity = McpAccessTokenEntity.create({
    userId: existingToken.getUserId(),
    teamId: existingToken.getTeamId(),
    teamRole: existingToken.getTeamRole(),
    tokenHash: newTokenHash,
    refreshTokenHash: newRefreshTokenHash,
    scopes: existingToken.getScopes(),
    clientName: existingToken.getClientName(),
    expiresAt: new Date(now + ACCESS_TOKEN_TTL_MS),
    refreshExpiresAt: new Date(now + REFRESH_TOKEN_TTL_MS),
  });

  await this.mcpAccessTokenRepository.save(newTokenEntity);

  // Revoke old token pair (rotation - prevents replay)
  await this.mcpAccessTokenRepository.revoke(existingToken.revoke());

  return Result.Success({
    accessToken: newAccessToken,
    refreshToken: newRefreshToken,
    expiresIn: ACCESS_TOKEN_EXPIRES_IN_SECONDS,
    tokenType: 'Bearer',
  });
}

We use refresh token rotation: every refresh issues a new refresh token and revokes the old one. If a refresh token is used twice, the second attempt fails - which signals a possible token theft.

The refresh token lives for 30 days. After that, the user re-authenticates through the browser. This is the only time they see the consent screen again.

The scope model

We have 25 scopes organized by domain and permission level:

invoices:read    invoices:write    invoices:delete
accounting:read  accounting:write  accounting:delete
companies:read   companies:write   companies:delete
clients:read     clients:write     clients:delete
products:read    products:write    products:delete
estimates:read   estimates:write   estimates:delete
sharing:read     sharing:write
teams:read       teams:write
billing:read
ai:read          ai:write

The pattern is {domain}:{level}. Three levels: read, write, delete. Some domains don't have all three - billing is read-only because there's no "create a subscription" tool.

This maps directly to our file organization from post 2. accountingReadTools.ts checks accounting:read. accountingWriteTools.ts checks accounting:write. The file name tells you the scope.

A typical connection grants 5-10 scopes. A freelancer connecting their personal AI assistant might grant everything. A company admin connecting a shared AI might grant invoices:read and accounting:read only - the AI can look at data but can't change anything.

Why remote is better than local for SaaS

	Local (stdio + API key)	Remote (HTTP + OAuth)
Setup	Edit JSON config file	Run one command
Security	Static key with full access	Scoped token, 1-hour expiry
Multi-tenancy	Manual key-per-team	Team picker in consent UI
Revocation	Generate new key, update config	Click "disconnect" in app settings
User consent	None - paste key and hope	Browser-based scope approval
Cross-device	Config file per device	Token syncs across Claude.ai devices
Updates	Reinstall/rebuild server binary	Server updates without client changes
Dependencies	Node.js + npm + binary	None (HTTP transport)

The last row matters more than you'd think. Local MCP servers require the user to have Node.js installed, run npx, and keep the process alive. Our remote server is just an HTTP endpoint. Claude Desktop, Claude.ai, ChatGPT, Cursor - they all connect with a URL. No local runtime.

Security model summary

What the AI can do:

Call any tool that's within the granted scopes
Read, create, update, or delete data within the selected team
Chain multiple tools in a single conversation

What the AI cannot do:

Access data from a team the user didn't select
Exceed the granted scopes (read-only connection stays read-only)
Impersonate another user (userId always comes from the token)
Use an expired or revoked token
Access data after the user is removed from the team (live membership check)

What the user controls:

Which team to grant access to
Which scopes to approve
When to disconnect (revoke from app settings)

If you're building a remote MCP server

Here's what we'd recommend based on what worked and what didn't:

Start with PKCE from day one. We briefly considered simple API keys as an MVP. Glad we didn't - retrofitting auth into a working server is painful, and users who connected with API keys would need to re-authenticate anyway.

Hash tokens before storing. This is a one-time cost (two lines of code) that eliminates an entire class of data breach scenarios.

Check team membership on every request. The extra database query is worth it. "Remove user from team" should mean "remove access immediately," not "remove access when their token expires."

Use domain:level scope naming. It scales. When we added the estimates domain, we added estimates:read, estimates:write, estimates:delete and it was obvious where each scope goes.

Return two content blocks. A human-readable summary and the full JSON data. The AI shows the summary to the user and uses the JSON for follow-up operations.

Try it

claude mcp add --transport http paperlink https://mcp.paperlink.online/api/mcp/mcp

You'll see the consent screen, pick a team, and be connected in about 10 seconds. 118 tools, scoped to exactly what you approved.

Your Claude Max Weekly Limit Runs Out in 3 Days. Here's Why (and the Fix)

Eugen — Thu, 23 Apr 2026 18:25:56 +0000

Your Claude Max weekly limit runs out in 3-4 days instead of 7.

You're paying $200/month. You're not imagining it.

We run Claude Code full-time building PaperLink - a document sharing and analytics platform. 8+ hour daily sessions, Clean Architecture across 4 layers, 30+ custom Claude skills, 9 automated hooks. We're not casual users - and we burned through limits faster than anyone we talked to.

We tracked this for months and found 4 root causes stacking simultaneously. None of them were obvious.

Root Cause #1: Anthropic Quietly Changed the Rules

In March 2026, Anthropic reduced peak-hour limits and removed the off-peak bonus that heavy users relied on.

There was no announcement. No changelog entry. We noticed when our weekly limit started dying on Wednesday instead of lasting until Sunday. The community confirmed it:

"Claude Code is the best coding tool I've ever used, for the 45 minutes a day I can actually use it."

This is the new baseline. Anthropic did not restore previous limits.

Root Cause #2: Cache Bug (10-20x Token Inflation)

Claude Code CLI versions 2.1.110 through 2.1.117 had a prompt caching bug that caused 10-20x token inflation per request.

What this means: a request that should have cost 5,000 tokens was costing 50,000-100,000. We run dozens of requests per session across our skill pipeline - the weekly limit was evaporating before we could finish a single feature.

Most people never noticed because token spend is not visible in the Claude Code UI by default.

Fix: Update to CLI version 2.1.118 or later.

# Check your current version
claude --version

# Update
npm i -g @anthropic-ai/claude-code@latest

Root Cause #3: The Most Expensive Configuration Possible

After the Opus 4.7 release, we were running the most expensive configuration possible:

Model: claude-opus-4-7 (most expensive model)
Effort level: xhigh (maximum thinking tokens per request)

We wanted the best output quality for our Clean Architecture codebase. But every single request - including trivial ones like "rename this variable" - was using the maximum token budget.

Fix: Pin the model to claude-opus-4-6. For 95% of coding tasks, the output quality is identical. The token cost is significantly lower.

{
  "model": "claude-opus-4-6",
  "effortLevel": "high"
}

Root Cause #4: Long Sessions Are Token Killers

We analyzed our usage patterns and found 87% of token spend came from agentic sessions lasting 8+ hours.

PaperLink has a full skill pipeline - business requirements, technical plans, implementation, code review, tests - all running through Claude Code. A single feature can mean 50+ tool calls in one session. Here's why that's expensive:

Context grows with every request/response pair
At 100,000 tokens of context, every new response costs roughly 2x what it costs at 50,000
After 6-7 hours, Claude starts "freelancing" - renaming variables, refactoring out-of-scope files, doing things you didn't ask for
Quality degrades, you correct it, corrections add more context, which increases cost further

It's a vicious cycle.

Fix: Set an auto-compact window and disable the 1M context option.

{
  "env": {
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "200000",
    "CLAUDE_CODE_DISABLE_1M_CONTEXT": "1"
  }
}

CLAUDE_CODE_AUTO_COMPACT_WINDOW at 200k tokens forces context compression before it balloons. CLAUDE_CODE_DISABLE_1M_CONTEXT caps the per-request token ceiling.

The Complete settings.json Fix

Here's the full configuration that doubled our weekly limit:

{
  "model": "claude-opus-4-6",
  "effortLevel": "high",
  "autoUpdatesChannel": "stable",
  "alwaysThinkingEnabled": false,
  "env": {
    "DISABLE_AUTOUPDATER": "1",
    "CLAUDE_CODE_DISABLE_1M_CONTEXT": "1",
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "200000"
  }
}

Two settings worth explaining:

alwaysThinkingEnabled: false - This was forcing extended thinking tokens on every request, even trivial ones. Extended thinking is powerful for complex architectural decisions - we use it when Claude needs to reason across domain, application, infrastructure, and presentation layers. But burning thinking tokens on "add a semicolon" is pure waste.

DISABLE_AUTOUPDATER: 1 - After the cache bug in versions 2.1.110-2.1.117, we pinned to a stable version. Auto-updates to buggy CLI versions can silently inflate your token spend for days before you notice.

One Thing I Removed

We had ENABLE_PROMPT_CACHING_1H in our env vars. Turns out Max subscription already gets 1-hour prompt cache TTL automatically. This variable was redundant - and according to the community, may have actually added overhead rather than helping.

The Result

Before	After
Weekly limit exhausted in 3-4 days	Weekly limit lasts 6-7 days
Frequent "limit reached" mid-session	Rare limit hits, usually end of week
Long sessions degrading quality	Shorter, higher-quality sessions

What Did NOT Change

Anthropic did not restore previous limits. This is the new normal.

These settings minimize your token spend within the current pricing model. If Anthropic changes limits again, the fundamentals still apply: control your model cost, control your context size, avoid buggy CLI versions.

Quick Checklist

Before your next session, verify:

[ ] CLI version >= 2.1.118 (claude --version)
[ ] Model pinned to claude-opus-4-6 (or claude-sonnet-4-6 for lighter tasks)
[ ] Effort level set to high, not xhigh
[ ] alwaysThinkingEnabled is false
[ ] Auto-compact window set to 200k
[ ] 1M context disabled
[ ] Auto-updater disabled (update manually when stable)
[ ] No redundant ENABLE_PROMPT_CACHING_1H env var

We're still pushing Claude Code hard every day on PaperLink - if we find more optimizations, we'll update this post.

What's the biggest Claude Code frustration you've hit? Drop your experience in the comments - curious how common these patterns are.

Your MCP Server Is a QA Engineer You Haven't Hired Yet

Eugen — Thu, 23 Apr 2026 07:49:07 +0000

We built 118 MCP tools for our SaaS and organized them into 19 files. Then we ran 722 manual test scenarios by talking to Claude. What we found changed how we think about MCP servers.

Unit tests verify that code does what you wrote. They do not verify that your data makes sense.

The accidental discovery

We built the MCP server for data entry - "record this expense," "create this invoice." Standard operations. Then we started asking different questions. Not "create X" but "show me everything that looks wrong."

The first one: "Show me all transactions without a category." Claude called list-transactions and returned entries we had forgotten about. Expenses recorded but never categorized. Not a code bug. A data gap. Invisible to every test we run.

That was the moment we realized: an AI with read access to multiple domains is a QA engineer. Not the kind that writes Playwright tests - the kind that audits your actual production data.

Cross-domain queries humans don't think to run

Here are the checks we now run regularly. Each one targets the boundary between two domains where no single test has jurisdiction.

Stuck state machines

"Which invoices have been in Sent status for more than 30 days?"

Claude calls list-invoices filtered by status, then checks dates. An invoice sitting in "Sent" for 47 days should have transitioned to "Overdue" automatically. If it didn't, the scheduled job failed, the client record was deleted, or there's a timezone bug. The AI doesn't fix these - it surfaces them.

Balance reconciliation

"Does the bank account balance match the sum of its transactions?"

Claude calls get-account-balances for current balances, then list-transactions filtered by account to sum recorded entries. If the numbers diverge, a transaction was missed during import or a balance sync failed silently. Both systems pass their own tests. The inconsistency lives between them.

Revenue consistency

"Compare total invoiced revenue with total recorded income in accounting."

Invoice totals are computed from line items. Accounting revenue comes from payment transactions. If these two numbers disagree, a payment was recorded without matching an invoice, or an invoice was paid but the income transaction was never created.

Ghost references

"Show me products referenced in invoices but marked as archived."

An archived product shouldn't appear on active invoices. If it does, the archive operation didn't cascade properly, or the invoice was created in a narrow window between the product lookup and the archive. Edge cases that unit tests don't model because they cross entity boundaries.

Dormant clients

"Which clients have zero invoices in the last 6 months?"

Not a bug - a business insight. But it's the same query pattern: cross-domain, read-only, using filters that no UI was designed to combine.

722 test scenarios: what we actually found

We didn't stop at ad hoc questions. We wrote 722 acceptance test scenarios and ran every one through Claude. Each tool got happy path tests, error handling, boundary values, unicode input, and cross-tool E2E flows.

We categorized results as PASS, SKIP, BUG-FIXED, or KNOWN-LIMITATION. The BUG-FIXED category is where it gets interesting.

Bug class 1: Zod coercion

MCP sends parameters as strings over JSON-RPC. Six of our list tools used z.number() for pagination params. Claude sends "3" as a string. Zod rejects it. The tools worked in our test suite (which passes native numbers) but failed through Claude.

Fix: z.number() to z.coerce.number() across all pagination params.

This is the kind of bug that automated tests miss because they test the code path, not the transport path. The Zod schema was correct TypeScript. It just didn't match the real-world input format.

Bug class 2: Required fields on partial updates

Three update tools (update-company, update-client, update-product) had name: z.string() in their schema. Name was required. But for a partial update, you might only want to change the phone number. Claude would send { phone: "..." } and Zod would reject it because name was missing.

Fix: z.string() to z.string().optional() for every field that shouldn't be mandatory on update.

Bug class 3: Missing ownership checks (IDOR)

update-document-status didn't verify that the status belonged to the authenticated team. A user could theoretically update another team's status by guessing the UUID. The web UI never exposed this because it only showed the user's own statuses. The MCP tool, being a raw API, had no such guard.

Fix: add teamId to the WHERE clause in the repository query. Same fix applied to delete-document-status.

This is the most important category. MCP tools are public API endpoints. If your web UI has implicit security (only showing the user's data), your MCP tools need explicit security (checking ownership in every query). The acceptance tests caught two IDOR vulnerabilities that would have passed code review.

Bug class 4: Method name mismatches

update-invoice called service.update() but the actual method was service.updateDocument(). TypeScript didn't catch it because the DI wiring used as never to bypass a complex generic. The tool compiled fine and would crash at runtime.

convert-estimate-to-invoice used require() instead of a static import, hiding another type mismatch. ESM context + require() = silent failure.

Fix: remove require(), use proper DI factory functions, fix the method names.

Bug class 5: Archived entities in list results

list-clients, list-companies, and list-products returned archived entities by default. The web UI filtered them out in the component. The MCP tool didn't. Claude would show the user a client they had already archived, they'd try to create an invoice for it, and get a confusing error.

Fix: filter archived entities by default, add includeArchived param for explicit requests.

The pattern: MCP tests the full stack

What these 5 bug classes have in common: they all live at integration boundaries that unit tests don't cross.

Unit test:     UseCase -> Mock Repository -> Assert result
MCP test:      Claude -> JSON-RPC -> Zod -> UseCase -> Prisma -> Response -> Claude

What unit tests verify:
  - Business logic
  - Input validation  
  - Error handling

What MCP tests add:
  - Transport coercion (string -> number)
  - Schema completeness (required vs optional)
  - Authorization at the API boundary (not UI boundary)
  - Response format (can the AI actually use the output?)
  - Cross-tool data integrity (tool A's output feeds tool B)

What MCP gives you that SQL doesn't

You could run consistency checks with SQL. The difference isn't capability - it's friction.

Authorization is built into every tool. Every MCP tool in our server filters by team automatically. With raw SQL, you write WHERE team_id = X on every query and hope nobody forgets.

No schema knowledge required. In our database, Account is the NextAuth OAuth model while FinancialAccount is a bank account, categories have polymorphic ownership (teamId OR userId, never both), and invoices and estimates live in separate tables with different schemas. The MCP tools abstract all of this away. You ask for "invoices" and get invoices.

Checks evolve without code changes. When you think of a new consistency check, you type it in English. "Which clients have invoices but no recorded payments in the last 90 days?" That check didn't exist before you asked - and it required no engineering work to create.

How to do this with your own MCP server

1. Identify boundary questions. Where should two domains agree? Revenue in invoices vs. revenue in accounting. Document access logs vs. NDA signatures. User counts vs. subscription seats.

2. Run 722 scenarios (or start with 10). Pick your most complex tool. Test: happy path, missing required params, invalid UUIDs, cross-team access, boundary values (amount: 0, limit: 101), unicode (Cyrillic descriptions, emoji). You'll find bugs on the first day.

3. Categorize what you find. PASS, BUG-FIXED, KNOWN-LIMITATION, SKIP. Track it. The BUG-FIXED count tells you how much value this approach adds. Ours was high enough that we made acceptance testing a standard step before every MCP release.

4. Make it routine. Ask your AI the boundary questions weekly. The data drifts. The questions stay relevant.

Try it

claude mcp add --transport http paperlink https://mcp.paperlink.online/api/mcp/mcp

Anatomy of a 118-Tool MCP Server: How We Organized the Chaos

Eugen — Thu, 23 Apr 2026 07:27:50 +0000

In the last post I showed what an AI does with 118 MCP tools. The first question people asked was: "How do you organize all of that without going insane?"

The honest answer: we didn't start with 118 tools. We started with 25 and hit every organizational problem you'd expect. This is what we ended up with after three rewrites.

The file structure

Every tool lives in one of 19 files, grouped by domain:

tools/
  accountingReadTools.ts         8 tools
  accountingWriteTools.ts        5 tools
  entityReadTools.ts             9 tools
  entityWriteTools.ts            9 tools
  entityDeleteTools.ts           3 tools
  documentReadTools.ts           3 tools
  documentCreateTools.ts        11 tools
  documentLifecycleTools.ts     10 tools
  categoryTools.ts               5 tools
  financialAccountTools.ts       5 tools
  currencyTools.ts               6 tools
  teamTools.ts                   6 tools
  billingTools.ts                2 tools
  aiInsightTools.ts              3 tools
  folderTools.ts                 6 tools
  fileTools.ts                   8 tools
  linkTools.ts                   4 tools
  sharingAnalyticsTools.ts       8 tools
  recurringTransactionTools.ts   7 tools
  types.ts                       shared type

Each file exports a single function:

export type ToolRegistrar = (server: McpServer, authInfo: McpAuthInfoDto) => void;

The entry point calls all 19 registrars:

function createMcpServer(authInfo: McpAuthInfoDto) {
  const server = new McpServer(
    { name: 'PaperLink', version: '1.0.0' },
    { instructions: MCP_INSTRUCTIONS }
  );

  registerAccountingReadTools(server, authInfo);
  registerAccountingWriteTools(server, authInfo);
  registerEntityReadTools(server, authInfo);
  // ... 16 more

  return server;
}

Adding a new domain is one file and one line in the entry point. No config, no registry, no plugin system.

Why read/write/delete are separate files

Version one had one file per domain: accountingTools.ts with all 13 tools. That worked until we added OAuth scopes.

Our OAuth consent screen lets users grant granular permissions: accounting:read, accounting:write, accounting:delete. A user might connect their AI assistant with read-only access to invoices but full write access to accounting.

When tools were in a single file, scope checks were scattered across the file with no clear boundary. Splitting by permission level made each file internally consistent: every tool in accountingReadTools.ts checks accounting:read, every tool in accountingWriteTools.ts checks accounting:write.

invoices:read    invoices:write    invoices:delete
accounting:read  accounting:write  accounting:delete
companies:read   companies:write   companies:delete
clients:read     clients:write     clients:delete
products:read    products:write    products:delete
estimates:read   estimates:write   estimates:delete
sharing:read     sharing:write
teams:read       teams:write
billing:read
ai:read          ai:write

25 scopes total. Each maps to a clear set of tools. You never wonder "does this tool need read or write?" because the filename tells you.

For smaller domains (categories, currencies, team), read and write stay in one file. We split when it starts to matter for permissions or when the file gets too long.

Tool naming: {verb}-{resource}

Most tools follow one pattern:

list-invoices
get-invoice
create-invoice
update-invoice
archive-invoice
restore-invoice
delete-invoice

Seven core verbs cover the CRUD lifecycle:

Verb	What it does	Reversible
`list`	Paginated collection	-
`get`	Single item by ID	-
`create`	New record	Yes (archive)
`update`	Modify existing	Yes (update again)
`archive`	Soft delete	Yes (restore)
`restore`	Undo archive	Yes (archive)
`delete`	Hard delete	No

Then there are domain-specific verbs for operations that don't fit the CRUD model: change-invoice-status, convert-estimate-to-invoice, record-invoice-payment, pause-recurring-transaction, generate-document-insight. About a dozen specialized verbs for a dozen specialized operations.

Batch operations get a plural noun: create-transactions (not create-transaction-batch). The AI figures it out from the plural.

This matters more than you'd think. AI models pattern-match on tool names. If you name one tool fetchInvoices, another getClients, and a third list-products, the model has to learn three conventions. Consistent naming means the model can predict tool names it hasn't seen yet.

Zod schemas as SSOT

Every tool input is a Zod schema:

server.registerTool(
  'list-invoices',
  {
    title: 'List Invoices',
    description: 'List invoices for the authenticated team.',
    inputSchema: z.object({
      status: z.string().optional().describe('Filter by status name'),
      clientName: z.string().optional().describe('Filter by client name'),
      dateFrom: coerceDateString().optional().describe('From date (YYYY-MM-DD)'),
      dateTo: coerceDateString().optional().describe('To date (YYYY-MM-DD)'),
      limit: z.coerce.number().int().min(1).max(100).optional(),
      offset: z.coerce.number().int().min(0).optional(),
    }),
    annotations: { readOnlyHint: true },
  },
  async (params) => { /* ... */ }
);

The Zod schema does three things at once:

Validation - bad input gets rejected before your handler runs
TypeScript types - params are fully typed inside the handler
JSON Schema - the MCP SDK generates the schema that AI clients see

No separate type definitions, no OpenAPI spec, no manual JSON Schema. One Zod object is the single source of truth.

The coercion problem

MCP sends parameters as JSON-RPC, and some clients serialize everything as strings. A number field might arrive as "10" instead of 10. A date might be "2024-03-15" or just 2024-03-15.

We wrote five coerce helpers to handle this:

coerceDateString()      // validates YYYY-MM-DD, accepts string
coerceAmount()          // positive number, min 0.01, max 999,999,999
coerceBoolean()         // "true"/"false" string -> boolean
coerceNullableString()  // "null" string -> null
coerceJsonArray(inner)  // JSON string -> parsed array

coerceJsonArray is the interesting one. Our create-transactions tool accepts a batch of up to 50 transactions. The AI sends them as a JSON string inside a single parameter:

{
  "transactions": "[{\"amount\": 12.50, ...}, {\"amount\": 8.00, ...}]"
}

The coercer parses the string, validates each element against the inner schema, and gives you a typed array. One helper, used in one tool, but it saved us from building a separate batch API.

Tool annotations

Every tool carries metadata hints:

// Read tools
{ readOnlyHint: true }

// Create tools
{ destructiveHint: false, idempotentHint: false }

// Update tools (modifying data = destructive + idempotent)
{ destructiveHint: true, idempotentHint: true }

// Restore tools (reversing a soft delete = safe + idempotent)
{ destructiveHint: false, idempotentHint: true }

// Archive/delete tools
{ destructiveHint: true, idempotentHint: false }

MCP clients can use these to decide whether to auto-approve a tool call or ask the user first. A readOnlyHint: true tool is safe to run without confirmation. A destructiveHint: true tool should probably ask first.

We adopted this convention early and it paid off. Some MCP clients show a different UI for destructive operations, and ours just worked.

The handler pattern

All 118 tool handlers follow the same five-step structure:

async (params) => {
  // 1. Check scope
  if (!authInfo.scopes.includes(SCOPE_ACCOUNTING_WRITE)) {
    return {
      content: [{ type: 'text', text: 'Insufficient scope - accounting:write required.' }],
      isError: true,
    };
  }

  // 2. Get use case from DI container
  const useCase = mcpUseCases.getCreateTransactionViaMcpUseCase();

  // 3. Execute (teamId/userId always come from auth, never from params)
  const result = await useCase.execute({
    ...params,
    teamId: authInfo.teamId,
    userId: authInfo.userId,
    memberRole: authInfo.teamRole,
  });

  // 4. Handle failure
  if (!result.isSuccess) {
    return {
      content: [{ type: 'text', text: result.errors.join(', ') }],
      isError: true,
    };
  }

  // 5. Return summary + structured data
  return {
    content: [
      { type: 'text', text: `Created transaction: ${data.description} - $${data.amount}` },
      { type: 'text', text: JSON.stringify(result.value, null, 2) },
    ],
  };
}

A few things to notice:

teamId and userId never come from parameters. They come from authInfo, which is populated from the OAuth token. The AI can't impersonate another user or access another team's data, even if it tries.

Two content blocks in every response. The first is a human-readable summary the AI can relay directly to the user. The second is the full JSON data the AI can parse and use for follow-up operations. This convention makes the AI's responses more natural without losing precision.

Result pattern, not exceptions. Every use case returns Result<T> with isSuccess, value, and errors. No try/catch in tool handlers, no exception-based flow control.

Use Cases: not raw queries

This is where we broke from what most MCP servers do.

The typical approach: tool handler takes params, runs a database query, returns the result. Fast to build, works fine for 10 tools.

At 118 tools, that approach means 118 handlers with database logic, validation, authorization checks, and business rules all mixed together. We'd already built these for our web app, so we reused them.

Every MCP tool calls a Use Case:

Tool handler (presentation layer)
  -> MCP Use Case (application layer)
    -> Domain Use Case (business logic)
      -> Repository (data access)

The MCP Use Cases are thin wrappers that add AI-friendly enrichment. For example, CreateTransactionViaMcpUseCase calls the same CreateTransactionUseCase that the web UI uses, then resolves account names and category paths so the AI can confirm with "Added $12.50 to Food & Dining > Groceries in your Wise USD account" instead of raw UUIDs.

This matters because business rules stay in one place. When we added a rule that transactions over $10,000 require approval, it worked in the web UI, the API, and the MCP server simultaneously. Zero duplication.

DRY patterns that actually helped

Polymorphic use cases

Companies, clients, and products share the same lifecycle: create, update, archive, restore, delete. Instead of nine separate use cases:

// One use case handles all three entity types
useCase.execute('company', { id, teamId, userId, memberRole });
useCase.execute('client',  { id, teamId, userId, memberRole });
useCase.execute('product', { id, teamId, userId, memberRole });

Three entity types, three operations each, nine tool handlers - but only three use case classes.

Category path resolver

Several tools need to show a category as a human-readable path: "Food & Dining > Groceries" instead of a UUID. We had the same ancestor-walking loop copy-pasted across four use cases before extracting it:

const resolved = await resolveCategoryPath(categoryId, categoryRepository);
// { name: "Groceries", path: "Food & Dining > Groceries" }

Scope constants

All 25 scope strings defined once:

export const MCP_SCOPE_ACCOUNTING_READ = 'accounting:read';
export const MCP_SCOPE_ACCOUNTING_WRITE = 'accounting:write';
// ... 23 more

Not exciting, but it means "rename a scope" is a single-line change with TypeScript catching every reference.

What we'd do differently

Start with the verb table. We defined verbs (list, get, create...) after building 60 tools. The first 60 had inconsistencies we had to fix. If we'd started with the verb convention, we'd have saved the refactor.

Split by permission from day one. The read/write file split happened at tool 40 when OAuth scopes forced it. It would have been easier at tool 1.

Invest in coerce helpers early. The MCP string coercion problem bit us on every tool. We wrote the helpers at tool 30. Should have been tool 1.

The one-liner

If you want to see all 118 tools in action:

claude mcp add --transport http paperlink https://mcp.paperlink.online/api/mcp/mcp

We Built 118 MCP Tools. Here's What AI Actually Does With Them

Eugen — Wed, 22 Apr 2026 14:00:16 +0000

A couple of months ago we finished exposing our SaaS through an MCP server. It now has 118 tools across 12 domains. I want to show what an AI actually does with all of that, because it's not really what we designed for.

PaperLink is a document-sharing and accounting SaaS. You connect Claude, ChatGPT, or any MCP client with one command and start talking to your data. Five examples from real conversations.

1. A receipt photo becomes 6 categorized transactions

Someone snaps a photo of a coffee-shop receipt. The AI reads six line items, calls create-transactions once with all six in a batch, assigns categories, and asks for confirmation before it saves anything. One tool call instead of six form submissions.

2. "Show me invoices stuck in SENT for 30+ days"

We built list-invoices so the UI could show a list of invoices. It takes filters as arguments, and those filters ended up doing more than we expected.

The AI composed a query we never built a UI for: status=SENT, sent over 30 days ago, status history never transitioned to OVERDUE. Five invoices came back that should have auto-transitioned and didn't. That's a bug we had been shipping without noticing.

3. "Upload this contract, password-protect it, expire Friday"

Three tools run from one sentence:

create-file-from-source uploads the file
create-link generates the protected share link
update-link sets the expiration date

The AI chains them, then asks "who should get access?" before sending.

4. "Transfer $500 from Wise to Mono"

Two accounts, different currencies. The AI calls get-exchange-rates, works out the destination amount, then calls create-transfer with both amounts paired and waits for confirmation. A transfer that takes about 45 seconds on a form takes roughly 10 seconds to type.

5. "Who actually read my proposal?"

The AI runs get-link-analytics, then get-top-viewers, then get-page-heatmap, and summarizes: "3 of 5 recipients opened it. One spent 6 minutes on the pricing page. The others skimmed." You get the answer without opening a dashboard.

The full map

Domain	Tools	Examples
Accounting & transactions	20	`create-transaction`, `create-transfer`, `get-category-breakdown`
Files & folders	14	`upload-file-from-url`, `create-folder`, `archive-file`
Clients & companies	14	`create-client`, `create-company`, `archive-company`
Document sharing & analytics	12	`create-link`, `get-page-heatmap`, `get-top-viewers`
Invoicing & payments	12	`create-invoice`, `record-invoice-payment`, `change-invoice-status`
Categories & accounts	10	`create-category`, `create-financial-account`
Estimates	8	`create-estimate`, `convert-estimate-to-invoice`
Products & services	7	`create-product`, `update-product`
Recurring transactions	7	`create-recurring-transaction`, `get-recurring-forecast`
Team & permissions	6	`invite-member`, `change-member-role`
Currency & exchange	6	`get-exchange-rates`, `add-team-currency`
AI insights & billing	5	`generate-document-insight`, `get-subscription-info`

Read, write, and delete tools live in separate files so OAuth scopes can stay granular.

Try it in 10 seconds

claude mcp add --transport http paperlink https://mcp.paperlink.online/api/mcp/mcp

The server is remote, so you get an OAuth consent screen with a team picker and scope checkboxes. Disconnect anytime from the app.

Next post: how we organized 118 tools across 19 files without writing the same boilerplate 118 times.