Menu
Scaffold a new MCP tool definition. Use when the user asks to add a tool, create a new tool, or implement a new capability for the server.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Scaffold a new MCP prompt template. Use when the user asks to add a prompt, create a reusable message template, or define a prompt for LLM interactions.
Scaffold a new MCP resource definition. Use when the user asks to add a resource, expose data via URI, or create a readable endpoint.
Scaffold a new service integration. Use when the user asks to add a service, integrate an external API, or create a reusable domain module with its own initialization and state.
Scaffold a test file for an existing tool, resource, or service. Use when the user asks to add tests, improve coverage, or when a definition exists without a colocated test file.
Authentication, authorization, and multi-tenancy patterns for `@cyanheads/mcp-ts-core`. Use when implementing auth scopes on tools/resources, configuring auth modes (none/jwt/oauth), working with JWT/OAuth env vars, or understanding how tenantId flows through ctx.state.
Reference for core and server configuration in `@cyanheads/mcp-ts-core`. Covers env var tables with defaults, priority order, server-specific Zod schema pattern, and Workers lazy-parsing requirement.
| name | add-tool |
| description | Scaffold a new MCP tool definition. Use when the user asks to add a tool, create a new tool, or implement a new capability for the server. |
| metadata | {"author":"cyanheads","version":"1.0","audience":"external","type":"reference"} |
Tools use the tool() builder from @cyanheads/mcp-ts-core. Each tool lives in src/mcp-server/tools/definitions/ with a .tool.ts suffix and is registered in the barrel index.ts.
For the full tool() API, Context interface, and error codes, read:
node_modules/@cyanheads/mcp-ts-core/CLAUDE.md
task: truesrc/mcp-server/tools/definitions/{{tool-name}}.tool.tssrc/mcp-server/tools/definitions/index.tsbun run devcheck to verifybun run dev:stdio or dev:http/**
* @fileoverview {{TOOL_DESCRIPTION}}
* @module mcp-server/tools/definitions/{{TOOL_NAME}}
*/
import { tool, z } from '@cyanheads/mcp-ts-core';
export const {{TOOL_EXPORT}} = tool('{{tool_name}}', {
title: '{{TOOL_TITLE}}',
description: '{{TOOL_DESCRIPTION}}',
annotations: { readOnlyHint: true },
input: z.object({
// All fields need .describe()
}),
output: z.object({
// All fields need .describe()
}),
// auth: ['tool:{{tool_name}}:read'],
async handler(input, ctx) {
ctx.log.info('Processing', { /* relevant input fields */ });
// Pure logic — throw on failure, no try/catch
return { /* output */ };
},
format: (result) => [{ type: 'text', text: JSON.stringify(result, null, 2) }],
});
Add task: true and use ctx.progress for long-running operations:
export const {{TOOL_EXPORT}} = tool('{{tool_name}}', {
description: '{{TOOL_DESCRIPTION}}',
task: true,
input: z.object({ /* ... */ }),
output: z.object({ /* ... */ }),
async handler(input, ctx) {
await ctx.progress!.setTotal(totalSteps);
for (const step of steps) {
if (ctx.signal.aborted) break;
await ctx.progress!.update(`Processing: ${step}`);
// ... do work ...
await ctx.progress!.increment();
}
return { /* output */ };
},
});
// src/mcp-server/tools/definitions/index.ts
import { existingTool } from './existing-tool.tool.js';
import { {{TOOL_EXPORT}} } from './{{tool-name}}.tool.js';
export const allToolDefinitions = [
existingTool,
{{TOOL_EXPORT}},
];
src/mcp-server/tools/definitions/{{tool-name}}.tool.ts.describe() annotations@fileoverview and @module header presenthandler(input, ctx) is pure — throws on failure, no try/catchauth scopes declared if the tool needs authorizationtask: true added if the tool is long-runningdefinitions/index.ts barrel and allToolDefinitionsbun run devcheck passesbun run dev:stdio or dev:http