Skip to main content
Glama
sdvsignal

one-tool

by sdvsignal
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

one-tool-mcp

A working sample of what an MCP Basic build from Kit looks like: one MCP tool, a described schema, the unhappy paths handled, a smoke prompt, and a clean removal path. Clone it, rename THING, and you have the shape.

It is deliberately one tool. A second tool, or a Cloudflare Worker, is a Build Packet, not a bigger version of this.

Try it without an API key

The tests run offline. No key, no network, no Claude.

npm install
npm test

15 tests. Most of them are unhappy paths, because that is where a bought tool actually fails on somebody: missing key, 401, 403, 429, a 503, a DNS failure, a body that is not JSON, and an empty result. Three of them stand up a real MCP client against the real server over an in-memory transport and call the tool, so the wiring is tested, not just the function.

Related MCP server: Things MCP

What is in here

File

What it is

src/search-things.js

The one tool. Takes its dependencies as an argument, which is why it is testable without a key.

src/server.js

Server wiring. Registers exactly one tool.

src/index.js

The entrypoint. Connects stdio and nothing else.

test/

The 15 tests above.

Add it to Claude Code

export THING_API_KEY=...
claude mcp add one-tool -- node /absolute/path/to/one-tool-mcp/src/index.js

Claude Desktop instead: add this to the config file and restart the app.

{
  "mcpServers": {
    "one-tool": {
      "command": "node",
      "args": ["/absolute/path/to/one-tool-mcp/src/index.js"],
      "env": { "THING_API_KEY": "..." }
    }
  }
}

Your key lives in your environment. It is not in this repo, and there is no default value that quietly works.

Smoke prompt

Type this to Claude. This is the test that it is really wired up:

Search THING for "onboarding" and show me the top 3.

You should get up to 3 results with names and ids. If nothing matches you get No THINGs matched "onboarding", which is correct and not a failure. Telling the model that an empty result is empty is most of why it stops retrying.

Remove it

claude mcp remove one-tool

Claude Desktop: delete the one-tool block and restart. The server keeps no state, so nothing is left behind.

Errors you may see

Message

Means

THING_API_KEY is not set

env var missing, or Claude was not restarted after you set it

THING rejected the key (401/403)

wrong or revoked key

THING rate limit hit (429)

wait, then retry

THING returned 503

their side, not yours

Could not reach https://...

network, or THING_BASE_URL is wrong

THING returned something that was not JSON

usually an HTML error page from a proxy

None of them return a stack trace. A tool that throws raw errors at the model makes it guess.

Making it yours

  1. Rename search_things for what it actually does, from the caller's point of view.

  2. Write the input schema before the implementation. Every field described, required vs optional explicit.

  3. Keep the description aimed at the model: say when to reach for the tool, not only what it is.

  4. Point THING_BASE_URL and the auth header at the real API.

  5. Run npm test, then run the smoke prompt in Claude. A passing test is not proof the tool works against the real API.

Want this built for your API instead

MCP Basic, $199. One tool, the schema, handoff notes, a smoke prompt and the enable/disable path, built against your API and tested against it before delivery. Need more than one tool, or a Worker? That is the Build Packet, $399.

Both are on the Kit page: https://kit-sdvsignal.pages.dev

MIT licensed. Use it for your own work, no attribution needed.

Available Tools

1 tool
search_thingsSearch thingsA

Search THING by free-text query. Use when the user asks what THINGs exist, or asks about a THING by name. Returns up to limit matches, newest first. Returns an empty list when nothing matches, which is not an error.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoHow many to return, 1 to 50. Defaults to 10.
queryYesFree-text search. Required.

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses useful behavioral traits beyond the schema: returns up to `limit` matches, newest first, and returns an empty list when nothing matches (not an error). However, with no annotations provided, the description carries the full burden, and it doesn't mention whether the operation is read-only, whether results are paginated beyond the limit, or any authentication requirements. The disclosed behaviors are valuable but not exhaustive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences with zero waste. The core purpose is front-loaded, and each sentence adds distinct information: what it searches, when to use it, and key behavioral details. No redundancy with the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple 2-parameter search tool with no output schema, the description covers the essential behaviors: result ordering, limit semantics, and empty-result handling. It doesn't describe the return format, but with no output schema and a simple search tool, the description is largely complete. The only minor gap is not explicitly stating the operation is read-only, but the description's wording implies a non-destructive search.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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 both parameters. The description adds the meaning of `limit` (up to `limit` matches) and the behavior of an empty result, but doesn't add syntax or format details beyond what the schema provides. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Search') and resource ('THING') and clarifies it is free-text query-based. It distinguishes the tool's purpose by explaining what user intents it serves ('what THINGs exist', 'asks about a THING by name'), though it doesn't name sibling tools because none are provided.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context for when to use the tool: when the user asks what THINGs exist or asks about a THING by name. It doesn't explicitly state when not to use it or name alternatives, but with no sibling tools provided, the usage context is reasonably complete.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev0.1.0
    • First observedsearch_things
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.8/5.0

Scored across 1 tool

Disambiguation5/5

With only one tool, there is no possibility of confusion between tools. The single tool's purpose is clearly defined, so an agent cannot misselect it.

Naming Consistency5/5

The one tool name follows a clear verb_noun pattern (search_things) in snake_case. With only one tool, there are no conflicting conventions to create inconsistency.

Tool Count3/5

A single tool is borderline thin for a server, but the tool itself is nontrivial and serves a focused search purpose. It does not warrant the 'too few' or 'trivial' lower scores, yet it lacks the breadth of a well-scoped 3-15 tool server.

Completeness2/5

The server only offers search, with no way to retrieve a specific THING by ID, create, update, or delete. This leaves significant gaps if the domain is intended to cover management of THINGs, making the surface incomplete.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Perplexity MCP Server

    jaacob
    A
    license
    B
    quality
    D
    maintenance
    Facilitates web search capabilities using Perplexity's API, allowing users to retrieve search results through Claude's interface.
    1
    8
    MIT

  • Synthetic Web Search MCP

    parnexcodes
    A
    license
    B
    quality
    D
    maintenance
    Exposes the Synthetic API as an MCP tool to enable web searching within Claude and other compatible applications. It provides formatted search results including titles, URLs, and text snippets for enhanced model context.
    1
    10 npm
    22
    MIT