Add MCP Tool

Add MCP Tool

Adds a new tool to the MCP server at https://mcp.moneymatter.app/mcp without breaking any drift check.

When to use

• User asks to add/expose a new MCP tool
• User wants an existing backend service callable by MCP clients (Claude Desktop, ChatGPT, etc.)
• Any time the tool list at packages/frontend/public/.well-known/mcp/server-card.json needs to grow

Architecture at a glance

Each MCP tool is a thin wrapper over an existing backend service:

Service (@services/...)
  ↓ called by
MCP tool file (packages/backend/src/services/mcp/tools/<name>.ts)
  ↓ registered in
createMcpServer() (packages/backend/src/services/mcp/server.ts)

Three metafiles stay in sync via drift tests:

• packages/frontend/public/.well-known/mcp/server-card.json — machine-readable tool list
• packages/frontend/public/skills/connect-moneymatter/SKILL.md — human-readable agent skill
• packages/frontend/public/.well-known/agent-skills/index.json — contains sha256 of the SKILL.md above

Checklist (complete every step)

When adding tool my_new_tool:

1. Create the tool file

Path: packages/backend/src/services/mcp/tools/my-new-tool.ts (kebab-case filename)

Use this template verbatim. Adjust imports, tool name, description, inputSchema, service call, and tool: string in trackMcpToolUsed.

import { trackMcpToolUsed } from '@js/utils/posthog';
import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { myService } from '@services/path/to/my-service';
import { z } from 'zod';

import { getUserId, jsonContent } from './helpers';

const inputSchema = {
  someId: z.number().describe('...'),
  optionalFilter: z.string().optional().describe('...'),
};

export function registerMyNewTool(server: McpServer) {
  server.registerTool(
    'my_new_tool',
    {
      description: 'What it returns and when an agent should call it. One sentence plus a hint on key fields.',
      inputSchema,
    },
    async (args, extra) => {
      const userId = getUserId({ extra });
      trackMcpToolUsed({ userId, tool: 'my_new_tool', clientId: extra.authInfo?.clientId });

      const result = await myService({ userId, ...args });
      return jsonContent({ data: result });
    },
  );
}

Rules:

• Tool name is snake_case (matches MCP convention) and must exactly equal the string in server-card.json.
• Register function is register<PascalCase>. File is <kebab-case>.ts.
• inputSchema is a plain object of Zod schemas (no outer z.object(...)), declared as a module-scope const, never inline inside registerTool(). Every MCP session builds its own McpServer, so an inline shape is rebuilt per session (zod v4 schemas are ~30 KB each).
• For tools with no inputs: omit inputSchema and drop the args parameter — handler becomes async (extra) => {...}.
• Always call getUserId({ extra }) first — it enforces auth and returns userId.
• Always call trackMcpToolUsed({ userId, tool, clientId: extra.authInfo?.clientId }) immediately after.
• Wrap the final response in jsonContent({ data }). Money instances auto-serialize to decimals via toJSON() in JSON.stringify.
• Use z.enum([...]) for enum args — match the style in search-transactions.ts.
• Dates: pass ISO strings in and convert with new Date(args.date) if the underlying service expects a Date.

2. Register the tool in server.ts

Add the import (alphabetical) and call it inside createMcpServer():

import { registerMyNewTool } from './tools/my-new-tool';
// ...
registerMyNewTool(server);

3. Update server-card.json

Path: packages/frontend/public/.well-known/mcp/server-card.json

Append to the tools[] array:

{
  "name": "my_new_tool",
  "description": "Short third-person description. Match what clients see."
}

The name MUST match the string in step 1 exactly. The drift test compares sorted arrays by string equality.

4. Update the connect-moneymatter SKILL.md

Path: packages/frontend/public/skills/connect-moneymatter/SKILL.md

Add a row to the "Available tools" table under the correct conceptual group (accounts vs investments vs analytics vs categories/tags). Use the SAME column layout (keep table alignment padded).

If the new tool introduces a new data convention (e.g. investments vs regular transactions), also add a bullet under "Data conventions".

5. Recompute SKILL.md sha256

shasum -a 256 packages/frontend/public/skills/connect-moneymatter/SKILL.md

Take the hex digest and update it in packages/frontend/public/.well-known/agent-skills/index.json:

{
  "skills": [
    {
      "name": "connect-moneymatter",
      ...
      "sha256": "<paste digest here>"
    }
  ]
}

Forgetting this step breaks agent-skills-drift.unit.ts.