MCP Toolbox
Provides web search capabilities via DuckDuckGo's Instant Answer API, returning ranked search results without requiring an API key.
Provides a fallback web search capability using Wikipedia's search API when DuckDuckGo is unavailable.
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., "@MCP Toolbox Search my stored docs for "MCP" and also calculate 23*19."
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.
MCP Toolbox — a Model Context Protocol server + client, from scratch
A clean, well-documented reference implementation of the Model Context Protocol (MCP): a server that exposes three real tools, and a client agent that discovers and calls them.

Document store — add, search (keyword-ranked), fetch, and list text documents. Persists to disk.
Web search — real web results via DuckDuckGo with a Wikipedia fallback. No API key required.
Calculator — safe arithmetic (no
eval; expressions are parsed and evaluated against a strict whitelist).
The client works in two modes:
Mode | Needs an API key? | What it does |
Offline (default) | No | Runs a scripted demo that exercises every tool and prints the results. Proves the full MCP round-trip. |
LLM | Yes ( | Hands the MCP tools to Claude and runs an agent loop; the model decides which tools to call. |
The same client code drives both modes — only who decides which tool to call changes. That is the core idea of MCP: the tool interface is uniform, so a simple scripted caller and a smart LLM caller use it identically.
Quickstart (60 seconds, no API key)
You need Python 3.10+.
# 1. From the project folder, create a virtual environment
python -m venv .venv
# 2. Activate it
source .venv/bin/activate # macOS / Linux
# .venv\Scripts\Activate.ps1 # Windows PowerShell
# .venv\Scripts\activate.bat # Windows cmd.exe
# 3. Install
pip install -e .
# 4. Run the offline demo — launches the server and calls every tool
python -m mcp_toolbox.clientYou'll see the client discover the server's tools and then run the calculator, the document store (search → add → fetch), and a web search, printing the structured result of each call.
Just want to see the tools the server exposes?
python -m mcp_toolbox.client --listRelated MCP server: Sentinel Core Agent
Turning on LLM mode (optional)
This lets Claude decide which tools to call to answer a question.
# Install the Anthropic SDK
pip install anthropic
# Add your key (get one at https://console.anthropic.com/ — pay-as-you-go)
cp .env.example .env
# then edit .env and set ANTHROPIC_API_KEY=sk-ant-...
# Ask a question; the agent will use the tools as needed
python -m mcp_toolbox.client --mode llm "What's stored about MCP transports, and what is 23 * 19?"A demo run costs a fraction of a cent. Without a key, everything else still works — the client simply falls back to the offline demo.
Run it with Docker (no Python setup)
If you'd rather not install anything locally, the demo runs in a container:
docker build -t mcp-toolbox .
docker run --rm mcp-toolboxFor LLM mode, pass your key in and override the command:
docker run --rm -e ANTHROPIC_API_KEY=sk-ant-... mcp-toolbox \
python -m mcp_toolbox.client --mode llm "What is MCP, and what is 12*9?"Project layout
mcp-toolbox/
├── README.md
├── demo.gif # the animation shown above
├── Dockerfile # run the demo in a container
├── pyproject.toml # packaging + console scripts + pytest config
├── requirements.txt
├── .env.example # copy to .env for LLM mode
├── run_demo.sh # convenience script: venv + install + demo
├── claude_desktop_config.example.json # use the server from Claude Desktop
├── .github/workflows/ci.yml # runs the tests on every push (Linux + Windows)
├── docs/
│ └── ARCHITECTURE.md # how MCP works and how this repo maps to it
├── src/mcp_toolbox/
│ ├── server.py # the MCP server (FastMCP over stdio)
│ ├── client.py # the client agent (offline + LLM modes)
│ └── tools/
│ ├── calculator.py # safe AST-based arithmetic
│ ├── document_store.py # in-memory store + keyword search + JSON persistence
│ └── web_search.py # keyless web search (DuckDuckGo → Wikipedia)
└── tests/
├── test_calculator.py
├── test_document_store.py
└── test_server_integration.py # launches the real server over stdioThe tools in tools/ are pure Python with no MCP dependency, so they're unit-testable in isolation and reusable elsewhere. server.py is a thin layer that exposes them as MCP tools; client.py is a thin layer that consumes them.
The tools in detail
Calculator — calculate(expression)
Parses the expression into Python's AST and walks it, allowing only whitelisted node types, constants (pi, e, tau) and functions (sqrt, sin, log, factorial, …). There is no path to eval, imports, or attribute access, so it's safe to expose to an autonomous agent. Division by zero and malformed input come back as structured errors.
Document store — add_document, search_documents, get_document, list_documents
An in-memory store that persists to a JSON file (~/.mcp_toolbox/documents.json by default; override with the MCP_TOOLBOX_DB env var). Search uses a transparent keyword scorer — term frequency in the body, with a ×3 boost for title matches and ×2 for tag matches — and returns ranked hits with snippets. It's deliberately simple so the ranking is easy to read; swapping in a vector store later wouldn't change the tool surface. The server seeds a few documents about MCP on first run so search has something to find.
Web search — web_search(query, limit)
Queries the DuckDuckGo Instant Answer API, falling back to the Wikipedia search API. Both are free and keyless. Network failures are caught and returned as an error field rather than raised, so the agent can react gracefully. (Some restricted/corporate networks block these endpoints; the tool degrades cleanly if so.)
Running the tests
pip install pytest pytest-asyncio
pytestThe suite covers the calculator, the document store, and — importantly — an end-to-end integration test that launches the real MCP server as a subprocess and calls its tools through a real MCP client session, proving tool discovery, argument passing, and structured results all work over stdio.
Using the server from Claude Desktop (or any MCP host)
Because this is a standard MCP server, any MCP-compatible host can use it — not just the bundled client. See claude_desktop_config.example.json for a ready-to-adapt config; point the command/args at your Python and the -m mcp_toolbox.server module, and the three tools show up in the host.
How it works (the short version)
MCP standardizes how an AI application talks to external tools. A host runs a client, and the client speaks MCP to one or more servers; each server advertises tools (plus resources and prompts). Here:
mcp_toolbox.serveris the server — it advertises six tools over the stdio transport.mcp_toolbox.clientis the client — it launches the server as a subprocess, callsinitialize,list_tools, andcall_tool, and either scripts the calls or lets an LLM choose them.
For the full walkthrough, see docs/ARCHITECTURE.md.
License
MIT — see LICENSE.
Available Tools
6 toolsadd_documentA
Store a new text document and return its generated id and metadata.
Args: content: The document body text (required, non-empty). title: An optional short title. tags: Optional list of tag strings for filtering/boosting search.
Inputs: content (required), tags, title.
calculateA
Safely evaluate an arithmetic expression and return the numeric result.
Supports + - * / // % ** parentheses, the constants pi/e/tau, and common math functions (sqrt, sin, cos, log, factorial, etc.). It does NOT use eval; expressions are parsed and evaluated against a strict whitelist.
Args: expression: e.g. "2 + 2", "sqrt(144)", "(3.5 * 4) ** 2", "log(e)".
Inputs: expression (required).
get_documentA
Fetch a single document's full content by its id.
Args: document_id: The id returned by add_document or search_documents.
Inputs: document_id (required).
list_documentsA
List all stored documents (newest first) with their ids and titles.
Inputs: no named parameters.
search_documentsA
Keyword-search the stored documents and return ranked matches.
Each result includes an id, title, relevance score, tags, and a snippet. Use get_document with a returned id to read the full text.
Args: query: Words to search for. limit: Maximum number of results (default 5).
Inputs: query (required), limit.
web_searchA
Search the public web (DuckDuckGo, with a Wikipedia fallback). No API key.
Returns a list of results, each with a title, url, and snippet. On network
failure it returns an error field instead of raising.
Args: query: The search query. limit: Maximum number of results (1-10, default 5).
Inputs: query (required), limit. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool has a clearly distinct purpose: document search, document creation, document retrieval, document listing, web search, and calculation. Even search_documents and list_documents are well differentiated by query-driven search versus full listing.
Most tools follow a clear verb_noun pattern (add_document, get_document, list_documents, search_documents). web_search inverts that order and calculate uses only a verb, but the overall naming is still readable and predictable.
Six tools is a reasonable, focused size for a document management helper with optional web search and calculation utilities. Each tool contributes a distinct capability without redundancy or bloat.
The document lifecycle is incomplete: add, get, list, and search are covered, but there is no update or delete operation for stored documents, which is a notable gap for a document store. web_search and calculate are one-shot utilities and don't need additional operations.
Related MCP Connectors
Cross-tool persistent memory and context for AI assistants over MCP.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Find, vet, and run MCP tools through a secure audited gateway with prompt-injection risk scoring
Turn a GitHub repo or docs site into agent-ready context: pack it or search it, over MCP.
Related MCP Servers
- AlicenseCqualityDmaintenanceA multi-tool MCP server that enhances local LLMs with web search, document reading, scholarly research, Wikipedia access, and calculator functions. Provides comprehensive tools for information retrieval and computation without requiring API keys by default.221MIT
- FlicenseNot gradedqualityDmaintenanceEnables file system operations, web scraping, and AI-powered search through MCP tools for use by LLM agents.1-
- FlicenseNot gradedqualityDmaintenanceExposes task management (add, list, complete tasks) and document search (RAG) as MCP tools for AI agents.-
- FlicenseNot gradedqualityDmaintenanceExposes a Retrieval-Augmented Generation pipeline as MCP tools, allowing users to index documents and query them through any MCP-compatible client like Claude or IDEs.-