How do I use toad-mcp-server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@toad-mcp-server search for documents about authentication" 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.

toad-mcp-server

by vola-trebla

Overview Schema Source Related Servers Discussions Admin

TypeScript

Hybrid

toad-mcp-server

🔌 MCP server exposing portfolio AI tools via Model Context Protocol. Connect to Claude Desktop and call Semantic Search, Eval Framework, and Prompt Management tools directly from chat.

🏗️ Architecture

┌─────────────────────┐    stdio / HTTP     ┌──────────────────────────┐
│   Claude Desktop    │◄────────────────-──►│    toad-mcp-server       │
│   (MCP Client)      │                     │                          │
└─────────────────────┘                     │  ┌────────────────────┐  │
                                            │  │ toad_search_docs   │──┼──► Semantic Search API
                                            │  ├────────────────────┤  │
                                            │  │ toad_run_eval      │──┼──► Eval Framework API
                                            │  ├────────────────────┤  │
                                            │  │ toad_system_status │──┼──► Health checks
                                            │  ├───────────────-────┤  │
                                            │  │ toad_list_prompts  │  │
                                            │  ├────────────────────┤  │
                                            │  │ toad_get_prompt    │  │
                                            │  └────────────────────┘  │
                                            └──────────────────────────┘

Related MCP server: claude-rag-mcp

🛠️ Tools

Tool	Description	Read-only
`toad_search_documents`	Semantic search over documents via natural language query	Yes
`toad_run_eval`	Run eval suite against a prompt variant, returns scores	No
`toad_system_status`	Health check all portfolio services (latency, status)	Yes
`toad_list_prompts`	List prompts with pagination and tag filtering	Yes
`toad_get_prompt`	Get prompt by name with version, template, score history	Yes

All tools support response_format: "markdown" | "json" where applicable.

📦 Resources

URI	Description
`toad://system/status`	Health status of all services (JSON)
`toad://prompts/{name}`	Get prompt by name with full metadata (JSON)

🚀 Quick Start

# Install
npm install

# Build
npm run build

# Run (stdio — for Claude Desktop)
npm start

# Run (HTTP — for remote/multi-client access)
TRANSPORT=http npm start

# Dev mode
npm run dev

🖥️ Claude Desktop Setup

Build the server:
```
npm run build
```

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "toad-mcp-server": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/absolute/path/to/toad-mcp-server",
      "env": {
        "SEMANTIC_SEARCH_URL": "http://localhost:3001",
        "EVAL_FRAMEWORK_URL": "http://localhost:3002"
      }
    }
  }
}

Restart Claude Desktop — tools appear automatically.

🔍 Testing with MCP Inspector

npx @modelcontextprotocol/inspector node dist/index.js

Opens a web UI to test each tool interactively.

⚙️ Environment Variables

Variable	Default	Description
`SEMANTIC_SEARCH_URL`	`http://localhost:3001`	Semantic Search Engine endpoint
`EVAL_FRAMEWORK_URL`	`http://localhost:3002`	Eval Framework endpoint
`TRANSPORT`	`stdio`	Transport mode: `stdio` or `http`
`PORT`	`3100`	HTTP transport port
`HOST`	`127.0.0.1`	HTTP transport bind address

📜 Scripts

Script	Description
`npm run build`	Compile TypeScript to `dist/`
`npm run dev`	Run with tsx (hot reload)
`npm start`	Run compiled server
`npm run lint`	ESLint check
`npm run format`	Prettier format

🧱 Tech Stack

TypeScript (NodeNext, strict)
@modelcontextprotocol/sdk — MCP server SDK
Zod v4 — input validation
ESLint + Prettier + Husky — code quality
GitHub Actions — CI (lint → format → build)

📄 License

ISC

Available Tools

5 tools

toad_get_promptA

Read-onlyIdempotent

Get a specific prompt by name with full metadata including version, score history, and template content.

Inputs: name (required), response_format.

toad_list_promptsA

Read-onlyIdempotent

List available prompts from the Prompt Registry. Supports pagination and optional filtering by tag.

Inputs: tag, limit, offset, response_format.

toad_run_evalA

Idempotent

Run an evaluation suite from the Eval Framework. Executes test cases against a prompt variant and returns scores and pass/fail results.

Inputs: suite (required), variant.

toad_search_documentsA

Read-onlyIdempotent

Search documents using semantic similarity. Connects to the Semantic Search Engine to find relevant documents based on a natural language query.

Inputs: query (required), limit.

toad_system_statusA

Read-onlyIdempotent

Check health of all portfolio services: Semantic Search API and Eval Framework. Returns status, latency, and error details for each component.

Inputs: no named parameters.

Tool Schema Changelog

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

Loading tool schema changelog…

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

A4.1/5.0

Scored 2026-09-06 10:50 across 5 tools

Disambiguation5/5

Each tool targets a distinct capability: semantic search, eval execution, system health, prompt listing, and prompt detail retrieval. The relationship between list_prompts and get_prompt is complementary rather than ambiguous.

Naming Consistency5/5

All tools follow the same `toad_` prefix with a clear verb_noun pattern: search_documents, run_eval, system_status, list_prompts, get_prompt. This makes the toolset highly predictable.

Tool Count5/5

Five tools is well-scoped for a specialized server covering search, evaluation, system health, and prompt registry access. Each tool earns its place without redundant or unnecessary entries.

Completeness3/5

The server supports read/search/run workflows, but lacks prompt registry write operations (create/update/delete) and any way to list available eval suites. Agents may encounter dead ends when trying to discover eval inputs or manage prompt lifecycle.

Maintenance

ActivityInactive

ResponsivenessNo recent community issues

Resources

Related MCP Connectors

Artificial Wit AI
com.artificialwit
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
ERP Systems CRM Knowledge & Memory
2
https://api.artificialwit.com/mcp
Station Zero
services.stationzero
One MCP server for the services your AI needs: memory, files, Microsoft 365, kanban and more.
Knowledge & Memory File Systems Workplace & Productivity
1
https://stationzero.services/mcp
Flowra
io.github.flowradev
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Agent Orchestration Autonomous Agents
11
https://mcp.flowra.dev/mcp
llm-orchestration-agent-2
ai.getvda
MCP-Native LLM Orchestration Agent
Agent Orchestration AI & Machine Learning
1
https://llm-orchestration-agent-2.getvda.ai/mcp

Related MCP Servers

ClaudeHopper
RAG Systems Vector Databases Developer Tools
Arborist-ai
A
license
Not graded
quality
D
maintenance
AI-powered MCP server that enables Claude and other LLMs to interact directly with construction documents, drawings, and specifications through advanced RAG and hybrid search capabilities.
Updated 2 years ago (2025-04-22 23:21 UTC)
8
MIT
claude-rag-mcp
RAG Systems Knowledge & Memory
VXConsulting
A
license
Not graded
quality
D
maintenance
MCP server providing RAG context and failure capture for Claude Code, enabling semantic search across project knowledge and storing/analyzing failures.
Updated 9 months ago (2026-02-02 12:10 UTC)
1
MIT
Fast Context MCP
Code Analysis Search Developer Tools
meimingqi222
A
license
B
quality
D
maintenance
Enables AI-driven semantic code search via natural language queries, integrating with MCP clients like Claude Desktop to retrieve relevant code context from any codebase.
Updated 9 months ago (2026-02-13 16:53 UTC)
1
MIT
Portfolio MCP Server
Search Developer Tools
ayush-s-tomar
A
license
A
quality
B
maintenance
An MCP server that exposes an AI project portfolio as queryable tools, allowing users to ask about projects, search by technology, or get details via natural language.
Updated 13 days ago (2026-11-01 22:59 UTC)
5
57 PyPI
1
MIT

toad-mcp-server

🏗️ Architecture

🛠️ Tools

📦 Resources

🚀 Quick Start

🖥️ Claude Desktop Setup

🔍 Testing with MCP Inspector

⚙️ Environment Variables

📜 Scripts

🧱 Tech Stack

📄 License

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

ClaudeHopper

claude-rag-mcp

Fast Context MCP

Portfolio MCP Server