opencode-mcp-tool-search

A dynamic MCP tool search plugin for OpenCode that reduces context usage by loading tools on-demand.

The Problem

When you have many MCP servers configured, each with multiple tools, the tool definitions can consume a significant portion of your context window:

• 50+ MCP tools can use ~67k tokens just for tool definitions
• This leaves less context for your actual conversation and code

The Solution

This plugin implements a search-based meta-tool pattern:

1. Instead of loading all tools upfront, provides a single mcp_tool_search meta-tool
2. Search for tools by name, description, or server
3. Call tools directly via mcp_call_tool

User: "What's the weather in NYC?"
    |
    v
OpenCode decides: need a weather tool
    |
    v
Calls: mcp_tool_search({ query: "weather" })
    |
    v
Search returns: [{ name: "get_weather", server: "weather-api", ... }]
    |
    v
Calls: mcp_call_tool({ server: "weather-api", tool: "get_weather", args: { location: "NYC" } })

Token Savings

Scenario	Token Usage
All tools loaded	~67k tokens
With this plugin	~500 tokens
Savings	~99%

Requirements

• OpenCode v1.0.0 or later
• Node.js 18+ or Bun 1.0+

Installation

npm install opencode-mcp-tool-search

Then add to your opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugins": ["opencode-mcp-tool-search"]
}

Important: When using this plugin, you must remove all mcpServers from your opencode.json. This plugin takes over MCP server management - configure your servers in the plugin instead (see Quick Start below).

Quick Start

1. Remove MCP Servers from OpenCode Config

Important: This plugin manages MCP server connections directly. You must remove any mcpServers from your opencode.json to avoid duplicate connections and conflicts.

Before (remove this):

{
  "$schema": "https://opencode.ai/config.json",
  "mcpServers": {
    "github": { ... },
    "filesystem": { ... }
  }
}

After:

{
  "$schema": "https://opencode.ai/config.json",
  "plugins": ["opencode-mcp-tool-search"]
}

2. Configure MCP Servers in the Plugin

Create a plugin configuration file and move your MCP server configs here:

// .opencode/plugin/mcp-search.ts
import { createMCPToolSearchPlugin } from "opencode-mcp-tool-search";

export const MCPToolSearch = createMCPToolSearchPlugin({
  mcpServers: [
    {
      name: "github",
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-github"],
      env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN },
    },
    {
      name: "filesystem",
      command: "npx",
      args: [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/allowed/dir",
      ],
    },
  ],
});

3. Use the Tools

Once configured, OpenCode can search and call MCP tools:

# Search for tools
mcp_tool_search({ query: "github pull request" })

# Call a tool
mcp_call_tool({ server: "github", tool: "create_pull_request", args: { ... } })

# List all servers
mcp_tool_search({ list_servers: true })

Available Tools

mcp_tool_search

Search for MCP tools by query.

Parameter	Type	Description
query	string	Search query (searches name, description, server instructions)
server	string	Optional: filter results to a specific server
list_servers	boolean	Optional: list all connected servers instead of searching

Examples:

// Search by keyword
mcp_tool_search({ query: "weather" });

// Filter by server
mcp_tool_search({ query: "pull request", server: "github" });

// List all servers
mcp_tool_search({ list_servers: true });

mcp_call_tool

Call an MCP tool on a specific server.

Parameter	Type	Description
server	string	Required: Server name
tool	string	Required: Tool name
args	object	Optional: Arguments to pass to the tool

Example:

mcp_call_tool({
  server: "github",
  tool: "create_issue",
  args: {
    owner: "myorg",
    repo: "myrepo",
    title: "Bug report",
    body: "Description of the issue",
  },
});

mcp_tool_info

Get detailed information about a specific tool, including its full JSON schema.

Parameter	Type	Description
tool_name	string	Name of the tool to inspect

Example:

mcp_tool_info({ tool_name: "create_pull_request" });

mcp_tool_search_status

Check plugin and server connection status.

Example:

mcp_tool_search_status();
// Returns: server count, connection status, tool count, any errors

Configuration

Full Configuration Example

// .opencode/plugin/mcp-search.ts
import { createMCPToolSearchPlugin } from "opencode-mcp-tool-search";

export const MCPToolSearch = createMCPToolSearchPlugin({
  // MCP servers to connect to
  mcpServers: [
    {
      name: "my-server",
      command: "node",
      args: ["./my-mcp-server.js"],
      env: { API_KEY: process.env.API_KEY },
      cwd: "/path/to/server",
      instructions: "This server provides weather and calendar tools",
      timeout: 30000, // Connection timeout in ms
    },
  ],

  // Search configuration
  maxResults: 10, // Maximum results to return (default: 10)
  fuzzyMatch: true, // Enable fuzzy matching for typos (default: true)
  minScore: 0.1, // Minimum match score 0-1 (default: 0.1)
  searchInstructions: true, // Search server instructions too (default: true)
});

Configuration Options

Option	Type	Default	Description
mcpServers	MCPServerConfig[]	[]	Array of MCP server configurations
maxResults	number	10	Maximum tools returned from search
fuzzyMatch	boolean	true	Enable fuzzy name matching
minScore	number	0.1	Minimum relevance score for results (0-1)
searchInstructions	boolean	true	Include server instructions in search

MCP Server Configuration

Option	Type	Required	Description
name	string	Yes	Unique server identifier
command	string	Yes	Command to start the server
args	string[]	No	Command arguments
env	Record<string, string>	No	Environment variables
cwd	string	No	Working directory
instructions	string	No	Server description (improves search)
timeout	number	No	Connection timeout in ms (default: 30000)

How Search Works

The search uses Fuse.js for fuzzy matching with weighted fields:

Field	Weight	Purpose
Tool name	50%	Primary identifier, handles typos
Tool description	35%	Semantic relevance
Server instructions	15%	Route to correct server

Search features:

• Fuzzy matching handles typos (e.g., "gihub" matches "github")
• Extended search syntax for advanced queries
• Results sorted by relevance score

Architecture

+----------------------------------------------------------+
|                      OpenCode                             |
+----------------------------------------------------------+
|  Plugin: opencode-mcp-tool-search                        |
|  +----------------------------------------------------+  |
|  |  State                                             |  |
|  |  - servers: Map<name, MCPServer>                   |  |
|  |  - allTools: MCPTool[]                             |  |
|  +----------------------------------------------------+  |
|                          |                                |
|  +----------------------------------------------------+  |
|  |              Tools (exposed to OpenCode)              |  |
|  |  - mcp_tool_search     (search tools)             |  |
|  |  - mcp_call_tool       (execute tools)            |  |
|  |  - mcp_tool_info       (inspect tools)            |  |
|  |  - mcp_tool_search_status (check status)          |  |
|  +----------------------------------------------------+  |
|                          |                                |
|  +----------------------------------------------------+  |
|  |              MCP Client                             |  |
|  |  - Stdio transport to MCP servers                  |  |
|  |  - Parallel server connections                     |  |
|  |  - Tool listing and execution                      |  |
|  +----------------------------------------------------+  |
+----------------------------------------------------------+
              |                    |                    |
        +-----+----+        +------+-----+       +------+-----+
        | MCP      |        | MCP        |       | MCP        |
        | Server 1 |        | Server 2   |       | Server N   |
        +----------+        +------------+       +------------+

Benefits

• Massive Token Savings: ~99% reduction in tool token usage
• No Protocol Changes: Works with standard MCP servers
• Transparent: MCP servers don't need any modifications
• Better Discovery: Search helps find the right tool faster
• Parallel Connections: Connects to all servers simultaneously

Tradeoffs

• Extra step to search before calling tools
• Requires good search queries to find the right tools
• Server instructions improve discoverability

Development

# Clone the repository
git clone https://github.com/francisco-m001/opencode-mcp-tool-search.git
cd opencode-mcp-tool-search

# Install dependencies
npm install
# or
bun install

# Build
npm run build
# or
bun run build

# Watch mode for development
npm run dev
# or
bun run dev

Project Structure

opencode-mcp-tool-search/
├── src/
│   ├── index.ts       # Plugin entry point and tool definitions
│   ├── search.ts      # Fuse.js search implementation
│   ├── mcp-client.ts  # MCP SDK client wrapper
│   ├── types.ts       # TypeScript interfaces
│   └── utils.ts       # Helper functions
├── package.json
├── tsconfig.json
└── README.md

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Related Projects

• OpenCode - AI-powered coding assistant
• Model Context Protocol - The MCP specification
• @modelcontextprotocol/sdk - Official MCP TypeScript SDK

License

MIT License - see LICENSE for details.