studio: Skill for Claude Code

Adding New MCP Tools to Studio

This guide documents the pattern for adding new MCP tools to Studio codebase. Follow this checklist to ensure consistency with existing tools.

Overview

MCP tools are exposed via the Model Context Protocol and allow programmatic management of resources. Each tool follows a consistent pattern with:

• Zod schemas for input/output validation
• defineTool for automatic tracing, metrics, and audit logging
• Access control via ctx.access.check()
• Better Auth integration via ctx.boundAuth

File Structure

When adding a new domain of tools (e.g., apiKeys, webhooks, secrets), create the following structure:

apps/api/src/tools/<domain>/
├── schema.ts     # Zod schemas for entities and operations
├── create.ts     # <DOMAIN>_CREATE tool
├── list.ts       # <DOMAIN>_LIST tool
├── update.ts     # <DOMAIN>_UPDATE tool  
├── delete.ts     # <DOMAIN>_DELETE tool
└── index.ts      # Barrel export

Step-by-Step Checklist

1. Create Schema File (schema.ts)

Define Zod schemas for:

• Entity schema: The resource returned in list/get operations
• Create input/output schemas: Input for creation, output includes created entity
• Update input/output schemas: Partial updates
• Delete input/output schemas: ID input, success confirmation output

// apps/api/src/tools/<domain>/schema.ts
import { z } from "zod";

// Entity schema (what's returned in list operations)
export const MyEntitySchema = z.object({
  id: z.string(),
  name: z.string(),
  // ... other fields
  createdAt: z.union([z.string(), z.date()]),
});

export type MyEntity = z.infer<typeof MyEntitySchema>;

// Create schemas
export const MyCreateInputSchema = z.object({
  name: z.string().min(1).max(255),
  // ... other fields
});

export const MyCreateOutputSchema = z.object({
  item: MyEntitySchema,
});

// List schemas
export const MyListInputSchema = z.object({
  // pagination, filters, etc.
});

export const MyListOutputSchema = z.object({
  items: z.array(MyEntitySchema),
});

// Update schemas
export const MyUpdateInputSchema = z.object({
  id: z.string(),
  // ... partial fields
});

export const MyUpdateOutputSchema = z.object({
  item: MyEntitySchema,
});

// Delete schemas
export const MyDeleteInputSchema = z.object({
  id: z.string(),
});

export const MyDeleteOutputSchema = z.object({
  success: z.boolean(),
  id: z.string(),
});