Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Antigravity Base MCP Server scaffold a new tool called get_weather with a Zod schema"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An enterprise-grade, clean, and extensible Base MCP (Model Context Protocol) Server Template built with TypeScript, Zod, Vite, and Vitest.
Designed to be your foundational starter kit: whenever you need a new MCP server with custom tools for a new project, simply copy this directory, define your tools in src/tools/, and use it instantly across Claude Desktop, Google Antigravity, Cursor, and VS Code.
No Manual Startup Required! You do NOT need to manually launch, keep terminal windows open, or run background daemons for this MCP server.
When an AI Agent (Claude, Antigravity, Cursor) sends its first request, the client automatically spawns bin/mcp-server.js on-demand over Stdio.
Self-Healing Bootstrap: If node_modules/ or dist/ is missing, the launcher automatically runs npm install and compiles the project on the fly in milliseconds before handling the request!
Related MCP server: MCP Server Boilerplate
⚡ Strict Protocol Compliance: Implements MCP Specification 2024-11-05 and JSON-RPC 2.0 (initialize, ping, tools/list, tools/call, resources/list, resources/read, prompts/list, prompts/get, completion/complete).
🛡️ Zero Stdout Pollution: Clean Stdio transport with all logger output strictly routed to stderr and optional file logging.
🧩 Modular Tool Architecture: Abstract BaseTool class with automatic Zod schema-to-JSON-Schema conversion and safe runtime validation.
🛠️ Instant Tool Generator: Run npm run new-tool <tool_name> to scaffold a new tool with types and schema in seconds.
🧪 Complete Test Suite: Integrated Vitest unit tests and real-stdio end-to-end integration tests (npm run test:all).
🖥️ Windows 1-Click Automation: .bat files for installation, building, testing, and running.
📖 Bilingual Guides: Includes English and comprehensive Persian documentation (GUIDE_FA.md).
Comparison Criteria | Building from Scratch (From 0) | Using Antigravity Base MCP |
Setup Time | 2 to 4 hours of tedious boilerplate | Under 1 minute (copy folder & rename) |
Stdio Stream Corruption | High risk ( | 100% Protected with stderr-isolated Logger |
Parameter Validation | Manual, error-prone JSON Schema definitions | Type-safe Zod Schemas with auto JSON Schema conversion |
Server Lifecycle | Manual script startup and background management | Autonomous on-demand wake-up and auto-build |
Error Handling | Repetitive try/catch boilerplate per tool | Standardized error wrappers with detailed diagnostics |
Testability | Hard to test without full LLM client | Built-in CLI & Vitest for immediate isolated testing |
Multi-Client Support | Unpredictable protocol quirks | Battle-tested across Claude, Antigravity, Cursor |
This template gives you the complete architecture to build:
🗄️ Database MCPs: Connect to SQLite, PostgreSQL, MongoDB, or Redis and expose query tools to AI agents.
📱 Flutter / Dart MCPs: Expose AST analyzers, automated widget generators, and emulator controllers.
💻 OS & File Automation MCPs: Create secure file management, process execution, and system diagnostics tools.
🌐 API Gateway & Webhook MCPs: Integrate third-party APIs, payments, messaging bots, and internal microservices.
📄 Dynamic Resources: Expose live project state, documentation, and database schemas directly to agents.
💡 Prompt Engineering Templates: Provide structured multi-step reasoning prompts for refactoring and security reviews.
base_mcp/
├── .agents/
│ └── skills/
│ └── base-mcp-starter/
│ └── SKILL.md # AI Agent skill documentation
├── bin/
│ ├── cli.ts # Interactive Developer CLI
│ ├── mcp-server.ts # Direct TS runner
│ └── mcp-server.js # Autonomous zero-config Node runner
├── src/
│ ├── index.ts # Main library exports
│ ├── server.ts # Core BaseMCPServer JSON-RPC router
│ ├── config/
│ │ └── index.ts # Server configuration & environment
│ ├── core/
│ │ ├── types.ts # Protocol types
│ │ ├── logger.ts # Stderr / file logger
│ │ ├── errors.ts # JSON-RPC error codes & classes
│ │ └── transport.ts # Stdio transport engine
│ ├── tools/
│ │ ├── base-tool.ts # Abstract base tool with Zod parsing
│ │ ├── registry.ts # Central tool registry
│ │ ├── index.ts # Tool registry loader & registrations
│ │ └── examples/
│ │ ├── echo.tool.ts # Echo sample tool
│ │ ├── system-info.tool.ts # System diagnostics sample tool
│ │ └── custom-template.tool.ts # Copy-paste blueprint
│ ├── resources/
│ │ ├── index.ts # Resource manager
│ │ └── examples/
│ │ └── sample-resource.ts # Sample dynamic resource
│ └── prompts/
│ ├── index.ts # Prompt manager
│ └── examples/
│ └── sample-prompt.ts # Sample prompt template
├── scripts/
│ ├── create-tool.ts # Tool scaffolding generator
│ ├── test-stdio.ts # End-to-end stdio protocol tester
│ └── export-schemas.ts # Schema exporter to JSON files
├── templates/
│ └── mcp_config.example.json # Client configuration snippets
├── tests/
│ ├── server.test.ts # Server protocol tests
│ └── tools.test.ts # Tool execution tests
├── package.json
├── tsconfig.json
├── vite.config.ts
├── vitest.config.ts
├── Build.bat
├── Run-Tests.bat
├── Start-Server.bat
└── Install-Dependencies.batnpm install
# or double click Install-Dependencies.batnpm run build
# or double click Build.batnpm run test:all
# or double click Run-Tests.bat# List all registered tools:
npm run cli list
# Call a tool directly:
npm run cli call echo '{"message": "Hello World!", "repeat": 2}'npm run new-tool calculate_taxThis generates src/tools/calculate-tax.tool.ts.
Open src/tools/calculate-tax.tool.ts:
import { z } from 'zod';
import { BaseTool } from './base-tool';
import { MCPToolCallResult } from '../core/types';
export const CalculateTaxSchema = z.object({
amount: z.number().positive().describe('Total amount in USD'),
taxRate: z.number().min(0).max(1).default(0.09).describe('Tax rate decimal (e.g. 0.09 for 9%)'),
});
export type CalculateTaxInput = z.infer<typeof CalculateTaxSchema>;
export class CalculateTaxTool extends BaseTool<typeof CalculateTaxSchema> {
public readonly name = 'calculate_tax';
public readonly description = 'Calculates total tax and grand total for a given amount.';
public readonly schema = CalculateTaxSchema;
public async execute(args: CalculateTaxInput): Promise<MCPToolCallResult> {
const tax = args.amount * args.taxRate;
const total = args.amount + tax;
return this.jsonResult({
originalAmount: args.amount,
taxRate: args.taxRate,
taxAmount: Math.round(tax * 100) / 100,
grandTotal: Math.round(total * 100) / 100,
});
}
}import { CalculateTaxTool } from './calculate-tax.tool';
export function createDefaultToolRegistry(): ToolRegistry {
const registry = new ToolRegistry();
// Register your new tool:
registry.register(new CalculateTaxTool());
return registry;
}Rebuild (npm run build) and test:
npm run cli call calculate_tax '{"amount": 100, "taxRate": 0.15}'claude_desktop_config.json){
"mcpServers": {
"my-mcp": {
"command": "node",
"args": ["C:/Users/ASUS/Desktop/flutter_project/base_mcp/bin/mcp-server.js"]
}
}
}mcp_config.json){
"mcpServers": {
"my-mcp": {
"command": "node",
"args": ["C:/Users/ASUS/Desktop/flutter_project/base_mcp/bin/mcp-server.js"],
"env": {
"MCP_LOG_LEVEL": "info"
}
}
}
}.cursor/mcp.json){
"mcpServers": {
"my-mcp": {
"command": "node",
"args": ["C:/Users/ASUS/Desktop/flutter_project/base_mcp/bin/mcp-server.js"]
}
}
}MIT License. Created by Antigravity Engineering.
Echoes back the input message with optional repetition and prefix formatting.
| Name | Required | Description | Default |
|---|---|---|---|
| prefix | No | Optional prefix to prepend to each line | |
| repeat | No | Number of times to repeat the message | |
| message | No | The text message to echo back |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the core behavior (echoing back input) and the optional modifiers (repetition, prefix). It does not cover edge cases like zero or negative repetition, but for a simple echo tool this is adequate. It adds meaningful behavioral context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, efficient sentence that front-loads the core action and mentions the two optional modifiers. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and a trivial return value, the description is sufficient. It explains the action and the parameters' purpose. Minor gaps like default behavior of repeat or prefix concatenation rules are not critical for an echo tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% – each parameter already has a clear description. The tool description's mention of 'optional repetition and prefix formatting' merely reiterates the schema. It adds no new semantic detail, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('echoes back'), a specific resource ('the input message'), and the optional behaviors (repetition and prefix formatting). It is unambiguous and naturally distinguished from the sibling tools, which are unrelated in function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly mention when to use this tool vs alternatives, but the siblings (get_system_info, my_custom_tool) are so different in purpose that no exclusion is necessary. The context is clear, though not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves current system diagnostics including OS, Node version, memory, and CPU info.
| Name | Required | Description | Default |
|---|---|---|---|
| includeCpu | No | Whether to include CPU architecture details | |
| includeMemory | No | Whether to include memory statistics |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It implies a read-only operation ('Retrieves') but does not describe the return format, potential side effects, or error conditions. It adds minimal context beyond the obvious.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the main action and lists the key content. It is concise with no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple diagnostic tool with no output schema, the description adequately states what it does but lacks usage context, output format, and any caveats. Given the low complexity, a 3 is reasonable, but it could be improved with a note on when to use it or what the response structure looks like.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers both parameters (includeCpu and includeMemory) with clear descriptions. The description mentions memory and CPU, aligning with the parameters, but does not add any extra meaning such as defaults, dependencies, or impact of omitting them. Baseline 3 is appropriate since schema coverage is 100%.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves system diagnostics, listing specific contents (OS, Node version, memory, CPU). It is specific and unambiguous, and the sibling names (echo, my_custom_tool) suggest they serve different purposes, so the distinction is implicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any guidance on when to use this tool versus alternatives, nor does it mention any conditions, prerequisites, or exclusions. It simply states what it does without contextual routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Detailed description of what this tool accomplishes, its expected input, and its output format.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of items to return | |
| query | No | Search query or target input string | |
| options | No | Optional execution configuration |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. The placeholder text does not disclose any side effects, permissions, rate limits, or return behavior. It merely states that a description exists, offering no substantive information about what the tool does or what happens when called.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single generic sentence, but it is not concise in the sense of conveying useful information—it is under-specified and content-free. It is a placeholder template, not an efficient communication of tool behavior. This resembles the under-specification case rather than true conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a nested object and three parameters, yet no output schema and no description of purpose or return format. The placeholder leaves the agent completely in the dark about what the tool does, what it returns, or how it relates to siblings. The definition is fundamentally incomplete for any real usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents all parameters (limit, query, options). According to the rubric, a high coverage baseline of 3 applies. The description adds no value beyond the schema, but it does not need to compensate since the schema is thorough.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description is a generic placeholder: 'Detailed description of what this tool accomplishes, its expected input, and its output format.' It provides zero actual information about the tool's function, resource, or scope. It is neither a specific verb+resource nor a restatement of the name; it is simply a template sentence that fails to convey any purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus its siblings (echo, get_system_info). The description contains no context about intended scenarios, prerequisites, or exclusions. An agent has no basis to decide whether to select this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0echoget_system_infomy_custom_toolScored across 3 tools
echo and get_system_info are clearly distinct operations, and my_custom_tool is not described in a way that directly overlaps with them. However, the placeholder description for my_custom_tool leaves its actual purpose ambiguous, so the set is not perfectly unambiguous.
The naming is inconsistent: echo uses a bare verb, get_system_info follows verb_noun, and my_custom_tool uses a vague custom label. There is no shared naming convention across the three tools.
Three tools is not an unreasonable number by itself, but the set feels like a minimal scaffold rather than a focused server. The unrelated utilities and placeholder custom tool make the count less defensible than it would be with a clear shared purpose.
The server lacks a coherent domain, so it is difficult to determine what complete coverage would look like. echo and get_system_info are isolated utilities, while my_custom_tool is an unspecified placeholder, leaving obvious gaps in any implied workflow.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
MCP-first toolbox for agents: KV storage, auth, queue, and utility tools. Free in early access.
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
