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., "@own-mcp-server What's the weather in San Francisco?"
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.
A custom Model Context Protocol (MCP) server, built from scratch in Node.js using the official @modelcontextprotocol/sdk. It runs over stdio and exposes four real, working tools that any MCP-compatible client (Claude Desktop, Claude Code, the MCP Inspector, etc.) can call.
This isn't a toy/hello-world stub — every tool actually does something:
Tool | What it does |
| Safely evaluates arithmetic expressions ( |
| Returns the current date/time in any IANA timezone (e.g. |
| Fetches live current weather for any place name via the free Open-Meteo API — no API key required. |
| A persistent notes store — notes are saved to |
own-mcp-server/
├── src/
│ ├── index.js # Server entry point — registers tools, connects stdio transport
│ └── tools/
│ ├── calculator.js # calculate
│ ├── time.js # get_current_time
│ ├── weather.js # get_weather (live API call)
│ └── notes.js # add_note / list_notes / delete_note (persisted to disk)
├── test/
│ └── test-server.mjs # End-to-end test: spawns the server and drives it with a real MCP client
├── data/
│ └── .gitkeep # notes.json is created here at runtime (gitignored)
├── .github/workflows/test.yml# CI: runs the test suite on every push/PR
├── claude_desktop_config.example.json
├── package.json
├── .gitignore
├── LICENSE
└── README.mdRelated MCP server: ai-mcp
McpServer from the SDK is instantiated once in src/index.js.
Each file in src/tools/ exports a register*Tool(server) function that calls server.registerTool(name, schema, handler) to add one or more tools.
src/index.js imports and calls each of those registration functions, then connects the server to a StdioServerTransport — this is what lets Claude Desktop / Claude Code talk to it as a subprocess over stdin/stdout.
Input validation for every tool is done with Zod schemas, so malformed calls are rejected with a clear error before your handler code ever runs.
Node.js 18 or newer
npm
git clone https://github.com/mayo-byte07/OWN-MCP-SERVER.git
cd OWN-MCP-SERVER
npm installYou normally don't run this directly — an MCP client launches it as a subprocess. But you can smoke-test it standalone:
npm startYou should see own-mcp-server running on stdio printed to stderr. The process will then sit waiting for MCP protocol messages on stdin — that's expected; press Ctrl+C to stop it.
An automated end-to-end test spawns the real server, connects a real MCP client to it, and calls every tool:
npm testExpected output includes a listing of all six tools and a successful call to each one (calculate, get_current_time, add_note, list_notes, delete_note, get_weather).
You can also poke at it interactively with the official MCP Inspector:
npm run inspectThis opens a web UI where you can call each tool by hand and see the raw request/response.
Open your Claude Desktop config file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Add an entry like the one in claude_desktop_config.example.json, pointing args at the absolute path to src/index.js on your machine:
{
"mcpServers": {
"own-mcp-server": {
"command": "node",
"args": ["/absolute/path/to/OWN-MCP-SERVER/src/index.js"]
}
}
}Restart Claude Desktop. The four tools should now show up under the 🔌 tools icon in a new conversation.
claude mcp add own-mcp-server -- node /absolute/path/to/OWN-MCP-SERVER/src/index.jsTo add a new tool:
Create a new file in src/tools/, e.g. src/tools/mytool.js.
Export a function that registers it:
import { z } from "zod";
export function registerMyTool(server) {
server.registerTool(
"my_tool",
{
title: "My Tool",
description: "What it does.",
inputSchema: { someInput: z.string().describe("What this argument is for") },
},
async ({ someInput }) => {
return { content: [{ type: "text", text: `You said: ${someInput}` }] };
}
);
}Import and call it in src/index.js alongside the others.
Add a case for it in test/test-server.mjs so CI keeps covering it.
Stdio transport is the simplest and most common way to run a local MCP server — the client launches your script as a child process and talks to it over stdin/stdout, so there's no port, no auth, and no network exposure to manage. If you need a remote/shared server later, the SDK also supports an HTTP + SSE transport (StreamableHTTPServerTransport) — see the SDK docs for that setup.
MIT — see LICENSE.
Save a short text note with a title, persisted to disk so it survives server restarts.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Short title for the note | |
| content | Yes | The note's content |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry behavioral disclosure on its own. It does so by stating that notes are persisted to disk and survive restarts, which is a non-obvious side effect. It stops short of describing return values or duplicate handling, but covers the core behavior.
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?
One sentence, front-loaded with the action, with every phrase earning its place. There is no filler or redundancy.
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 is simple and the schema covers both parameters, so the description covers the essential operation and persistence. However, with no output schema, the description doesn't say what the tool returns after saving, which an agent might need to handle the result.
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 parameters are already fully documented. The description's phrase 'with a title' adds no new meaning beyond the schema.
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?
States a specific verb ('Save') and resource ('short text note'), with a clear scope. The persistence detail further distinguishes it from ephemeral operations, and the sibling names make its role obvious.
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 implies when to use the tool – to save a note – but never contrasts it with alternatives like list_notes or delete_note, nor states when not to use it. The guidance is implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Evaluate a basic arithmetic expression (+, -, *, /, parentheses, decimals). Example: '(4 + 5) * 2 / 3'.
| Name | Required | Description | Default |
|---|---|---|---|
| expression | Yes | Arithmetic expression to evaluate, e.g. '2 + 2 * (3 - 1)' |
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. It discloses the supported operators and gives an example, which is helpful, but it does not state what happens on invalid input, division by zero, or overflow, nor does it describe the return format (number, string, precision). For a simple calculator the behavior is fairly predictable, but these gaps remain.
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?
One sentence plus an illustrative example with zero waste. The purpose is front-loaded in the first few words, and the example reinforces the message efficiently.
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 single-parameter calculator with 100% schema coverage, the definition is mostly complete. It covers scope and usage. Minor gaps—return type and error behavior—are acceptable for such a simple, low-risk tool, though stating the result format would make it fully self-contained.
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 coverage is 100%, so the schema already documents the single 'expression' parameter. The description adds the supported operator list and an example, which marginally extends the schema's own example, but does not add meaningful new semantics beyond what the schema already conveys. Baseline 3 applies given the high coverage.
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?
States a specific verb ('Evaluate'), the resource ('arithmetic expression'), and the exact scope (+, -, *, /, parentheses, decimals) with a concrete example. The sibling tools (get_weather, get_current_time, add_note, etc.) are all clearly distinct, so there is no ambiguity about what this tool does.
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 makes clear it handles 'basic' arithmetic, which implies it is not for advanced math, but there is no explicit when-to-use or when-not-to-use statement. Sibling differentiation is not needed since no sibling overlaps, but the guidance is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a saved note by its id.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The id of the note to delete, as returned by add_note or list_notes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden of disclosing behavior. 'Delete' does signal a destructive action, but the description does not state whether deletion is permanent, what happens for invalid or missing ids, or what response is returned—important gaps for a mutation tool with no output 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?
The description is a single short sentence that front-loads the action and target. There is no filler, repetition, or unnecessary detail.
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 one-parameter tool with complete schema coverage, the core call shape is clear: the agent knows what to do and what id to pass. However, with no annotations and no output schema, the description omits return/error behavior and permanence, leaving it minimally complete for a destructive operation.
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 input schema already fully documents the only parameter, including its origin ('as returned by add_note or list_notes'), so schema coverage is 100%. The description's 'by its id' adds no new semantic meaning beyond the schema, making the baseline 3 appropriate.
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 specific verb ('Delete'), a resource ('a saved note'), and the mechanism ('by its id'). This clearly differentiates it from the sibling add_note and list_notes tools without requiring the agent to infer intent from the tool name.
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 implies the tool is for removing an existing saved note, and the 'saved note' wording indicates the note must already exist. However, it does not explicitly explain when to choose this over add_note/list_notes or mention that the id should be obtained from those tools, so usage guidance is mostly implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current date and time, optionally in a specific IANA timezone (e.g. 'Asia/Kolkata'). Defaults to UTC.
| Name | Required | Description | Default |
|---|---|---|---|
| timezone | No | IANA timezone name, e.g. 'Asia/Kolkata'. Defaults to 'UTC'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations provided, so the description carries the full burden. The description discloses the default timezone (UTC) and that it accepts an optional timezone, which is useful. However, it doesn't disclose the return format (e.g., ISO string, human-readable), which could be important for agents integrating the output. This is a minor gap.
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 concise, two sentences, front-loaded with the core purpose and then details the optional parameter. No wasted words, well-structured.
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?
Given that this is a simple tool with one optional parameter and no output schema, the description is largely complete. It mentions the default timezone and an example. The only missing piece is the return format, which could be inferred but would be helpful to state. Still, for a time tool, this is sufficient.
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 schema already documents the timezone parameter, including its type and default. The description adds a concrete example ('Asia/Kolkata') and reaffirms the default, which is slightly redundant but helpful. The description doesn't add much beyond the schema, so baseline 3 is appropriate.
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's purpose: getting current date and time, optionally in a specific IANA timezone. This is a clear verb+resource description that distinguishes it from sibling tools like calculate and get_weather. However, it does not explicitly differentiate itself from any sibling that might also provide time-related data, though none of the listed siblings do.
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 gives a clear sense of when to use the tool: whenever current date/time is needed. It mentions the timezone parameter and default behavior. However, it doesn't explicitly state when not to use it or mention alternatives, but given the sibling list, this tool is the only one providing time, so the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current live weather for a city or place name (e.g. 'Muzaffarnagar' or 'Tokyo, Japan'). Uses the free Open-Meteo API.
| Name | Required | Description | Default |
|---|---|---|---|
| location | Yes | City or place name to look up |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden of behavioral disclosure. It mentions 'Uses the free Open-Meteo API' which hints at an external dependency, but it does not disclose potential failures (e.g., invalid location), rate limits, response structure, or whether it is a read-only operation. For a tool with no annotations, this is a significant gap.
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 two sentences with zero fluff. The core purpose and input format are front-loaded, and the API note is brief. Every sentence earns its place, and the structure is easy to scan.
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 one-parameter read-only tool, the description covers the what, the input, and the external API. However, since there is no output schema, the description should at least hint at what the response contains (e.g., temperature, conditions) or error behavior. This is missing, so the description is functional but not fully complete for an agent deciding how to interpret the result.
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% for the single 'location' parameter, and the schema already describes it as 'City or place name to look up'. The description adds helpful examples ('Muzaffarnagar', 'Tokyo, Japan') and clarifies it's live weather, but these are incremental, not substantive additions. The baseline of 3 applies because the schema already handles parameter semantics.
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 specific verb ('get') and resource ('current live weather') along with the input type (city or place name). The examples clarify the expected input format, and the sibling tools (calculate, notes, time) are clearly unrelated, so this tool is easily distinguished without needing to inspect schemas.
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 clearly implies when to use this tool (whenever current weather is needed) and provides context for the input format. However, it does not explicitly mention alternatives or when not to use it, which is acceptable given the sibling list contains no weather-related alternatives. It lacks explicit when-not guidance, so a 4 is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all saved notes with their ids, titles, and creation times.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the behavioral disclosure burden. It states the return fields (ids, titles, creation times) but does not explicitly mention that it is a read-only operation or any other behavioral traits such as authentication or side effects. The read-only nature is implied by 'list', but not stated, leaving room for interpretation.
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 with no unnecessary words. It front-loads the action and resource, then lists the returned fields. Perfectly concise and well-structured.
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 zero-parameter list tool, the description tells the agent exactly what it returns (ids, titles, creation times) and that it covers all saved notes. There is no output schema, so the description sufficiently covers the return value. No essential information is missing for correct invocation.
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 tool has zero parameters, and the schema is trivially covered at 100%. Per the guideline for 0 parameters, the baseline is 4. The description adds no parameter-specific details, but none are needed since there are no inputs.
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 uses a specific verb and resource: 'List all saved notes'. It clearly distinguishes from siblings like add_note, delete_note, calculate, etc., which perform different operations. There is no ambiguity about what this tool does.
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 usage context is clear: it is for retrieving all notes, which is obviously distinct from the sibling tools (add, delete, calculate, etc.). However, it does not explicitly state when to use it over alternatives or any exclusions, but the purpose alone makes the intended usage evident.
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.0add_notecalculatedelete_noteget_current_timeget_weatherlist_notesScored across 6 tools
Each tool has a clearly distinct purpose: arithmetic, time, weather, and note management. There is no overlap or ambiguity between any of the six tools.
All tool names follow a consistent lowercase verb-first pattern such as get_weather, add_note, list_notes, and delete_note. The single verb 'calculate' is slightly generic but still fits the naming style.
Six tools is a well-scoped size for a small utility server. Each tool serves a distinct function without excess or redundancy.
The note feature covers add, list, and delete, but there is no way to retrieve the full content of a single note or update it. Since notes are simple and list provides metadata, this is a minor gap rather than a critical one.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
The official Model Context Protocol server for Ambee. It gives any MCP-compatible AI assistant — Claude, ChatGPT, Cursor, VS Code, Ollama, and more direct access to live air quality, pollen, and weather data. To get started, including information on signing up and obtaining your Ambee key, check out the Ambee documentation on https://docs.ambeedata.com
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
60+ units, live FX, timezones, and date arithmetic for AI agents.
