How do I use Heroku MCP Tool Search Server?

1. Click on "Install 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., "@Heroku MCP Tool Search Server find a tool that can summarize long PDF documents" 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 Tool Search Server

The Problem: When you give Claude 50+ tools, two things break:

Context bloat - Tool definitions eat 10-20K tokens, leaving less room for actual work
Selection accuracy - Claude gets confused and picks wrong tools when there are too many

The Solution: Instead of loading all tools upfront, Claude searches for tools and loads only what it needs.

Without Tool Search:              With Tool Search:
┌─────────────────────┐           ┌─────────────────────┐
│ Load 100 tools      │           │ Load 1 search tool  │
│ (20K tokens)        │           │ (200 tokens)        │
│                     │           │                     │
│ Claude picks wrong  │           │ Claude searches:    │
│ tool 30% of time    │           │ "weather" → 2 tools │
│                     │           │                     │
│ Context nearly full │           │ 95% context free    │
└─────────────────────┘           └─────────────────────┘

How It Works

You register your tools with this server (via REST API)
Claude gets access to search tools (tool_search_bm25, tool_search_semantic, tool_search_regex)
When Claude needs a tool, it searches → gets back tool names → uses them

Three search methods:

BM25 - Keyword matching ("weather" finds get_weather, get_forecast)
Semantic - Meaning-based ("send a message" finds send_email)
Regex - Pattern matching (get_.* finds all getter tools)

Deploy to Heroku

Or manually:

heroku create my-tool-search
heroku buildpacks:set heroku/python
git push heroku main
heroku ai:models:create claude-4-sonnet --as INFERENCE

Register Your Tools

curl -X POST https://your-app.herokuapp.com/tools \
  -H "Content-Type: application/json" \
  -d '{
    "name": "get_weather",
    "description": "Get current weather for a location",
    "input_schema": {
      "type": "object",
      "properties": {"location": {"type": "string"}},
      "required": ["location"]
    }
  }'

Test It

export INFERENCE_KEY=$(heroku config:get INFERENCE_KEY -a my-tool-search)
export INFERENCE_URL=$(heroku config:get INFERENCE_URL -a my-tool-search)

curl -s "$INFERENCE_URL/v1/agents/heroku" \
  -H "Authorization: Bearer $INFERENCE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-4-sonnet",
    "messages": [{"role": "user", "content": "Find tools for checking weather"}],
    "tools": [{"type": "mcp", "name": "mcp-tool-search/tool_search_semantic"}]
  }'

API Reference

Endpoint	Description
`POST /tools`	Register a tool
`GET /tools`	List all tools
`DELETE /tools/{name}`	Remove a tool
`GET /health`	Health check

MCP Tools

Tool	Use Case
`tool_search_bm25`	Find tools by keywords
`tool_search_semantic`	Find tools by meaning
`tool_search_regex`	Find tools by pattern
`list_all_tools`	List all registered tools