Search MCP

The Universal MCP Server exposes tools for your workflows and is designed for prompt-first usage in MCP-compatible clients.

Installation

Prerequisites

Node.js 18+
Set SEARCH_MCP_... in your environment

Get an API key

If your tools require an external API, obtain a key from the provider’s docs/console.
Otherwise, you can skip this step.

Build locally

cd /path/to/search-mcp
npm i
npm run build

Setup: Claude Code (CLI)

Use this one-liner (replace with your real values):

claude mcp add URL-Context-MCP -s user -e SEARCH_MCP_API_KEY="sk-your-real-key" -- npx @taiyokimura/url-context-mcp@latest

To remove:

claude mcp remove Search MCP

Setup: Cursor

Create .cursor/mcp.json in your client (do not commit it here):

{
  "mcpServers": {
    "url-context-mcp": {
      "command": "npx",
      "args": ["@taiyokimura/url-context-mcp@latest"],
      "env": { "SEARCH_MCP_API_KEY": "sk-your-real-key" },
      "autoStart": true
    }
  }
}

Other Clients and Agents

VS Code

Install via URI or CLI:

code --add-mcp '{"name":"url-context-mcp","command":"npx","args":["@taiyokimura/url-context-mcp@latest"],"env":{"SEARCH_MCP_API_KEY":"sk-your-real-key"}}'

Claude Desktop

Follow the MCP install guide and reuse the standard config above.

LM Studio

Command: npx
Args: ["@taiyokimura/url-context-mcp@latest"]
Env: SEARCH_MCP_API_KEY=sk-your-real-key

Goose

Type: STDIO
Command: npx
Args: @taiyokimura/url-context-mcp@latest
Enabled: true

opencode

Example ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "url-context-mcp": {
      "type": "local",
      "command": ["npx", "@taiyokimura/url-context-mcp@latest"],
      "enabled": true
    }
  }
}

Qodo Gen

Add a new MCP and paste the standard JSON config.

Windsurf

See docs and reuse the standard config above.

Setup: Codex (TOML)

Example (Serena):

[mcp_servers.serena]
command = "uvx"
args = ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server", "--context", "codex"]

This server (minimal):

[mcp_servers.url-context-mcp]
command = "npx"
args = ["@taiyokimura/url-context-mcp@latest"]
# Optional:
# SEARCH_MCP_API_KEY = "sk-your-real-key"
# MCP_NAME = "url-context-mcp"

Configuration (Env)

SEARCH_MCP_API_KEY: Your API key (if applicable)
MCP_NAME: Server name override (default: url-context-mcp)

Available Tools

web_search
- inputs: object { query: string (required), count?: number, offset?: number, safeSearch?: 'off'|'moderate'|'strict', country?: string, freshness?: 'pd'|'pw'|'pm'|'py', enableRichCallback?: boolean }
- outputs: object (Brave Web Search API JSON)
local_pois
- inputs: object { ids: string[] (1-20) }
- outputs: object (Local POI API JSON)
local_descriptions
- inputs: object { ids: string[] (1-20) }
- outputs: object (Local descriptions API JSON)
rich_fetch
- inputs: object { callback_key: string }
- outputs: object (Rich results JSON)

Example invocation (MCP tool call)

{
  "tool": "web_search",
  "inputs": {
    "query": "weather in munich",
    "enableRichCallback": true
  }
}

Troubleshooting

401 auth errors: check SEARCH_MCP_API_KEY
Ensure Node 18+
Local runs: npx search-mcp after npm run build
Inspect publish artifacts: npm pack --dry-run

References

MCP SDK: https://modelcontextprotocol.io/docs/sdks
Architecture: https://modelcontextprotocol.io/docs/learn/architecture
Server Concepts: https://modelcontextprotocol.io/docs/learn/server-concepts
Specification: https://modelcontextprotocol.io/specification/2025-06-18/server/index
Brave Search API: https://api.search.brave.com/app/documentation

Name Consistency & Troubleshooting

Always use CANONICAL_ID (url-context-mcp) for identifiers and keys.
Use CANONICAL_DISPLAY (URL-Context MCP) only for UI labels.
Do not mix legacy keys after registration.

Consistency Matrix:

npm package name → @taiyokimura/url-context-mcp
Binary name → url-context-mcp
MCP server name (SDK metadata) → url-context-mcp
Env default MCP_NAME → url-context-mcp
Client registry key → url-context-mcp
UI label → URL-Context MCP

Conflict Cleanup:

Remove any stale keys (e.g., old display names) and re-add with url-context-mcp only.
Cursor: configure in the UI; this project intentionally omits .cursor/mcp.json.