Seahorse MCP Hybrid Search Server (npx)

Run the Seahorse Hybrid Search MCP server anywhere via npx. This package wraps a Python FastMCP server and bootstraps a local Python virtual environment on first run.

Features

• v2 API Support: Uses the new POST /v2/data/search endpoint
• Search Modes:
  • dense: Semantic vector search using BGE-M3 embeddings
  • sparse: Keyword search using BM25 tokenization
  • hybrid: RRF (Reciprocal Rank Fusion) of dense and sparse results
• Auto-embedding: Natural language queries are automatically converted to embeddings server-side
• Adjacent Chunks: Retrieve previous/next chunks for context expansion

Install and Run

npx @dn-inc/seahorse-mcp-seahorse --api-url https://YOUR_TABLE_ID.api.seahorse.dnotitia.com --api-key YOUR_API_KEY

Options

| Flag | Environment Variable | Description | |------|---------------------|-------------| | --api-url | SEAHORSE_API_URL | Seahorse API base URL (required) | | --api-key | SEAHORSE_API_KEY | Seahorse API key (required) | | --verify-ssl | SEAHORSE_VERIFY_SSL | Verify SSL certificates (default: false) | | --tool-desc | TOOL_DESC | Knowledge-domain description surfaced in the search tool description | | --reranker-url | RERANKER_URL | Reranker endpoint (Cohere/OpenRouter-compatible). Rerank is off unless both URL and model are set | | --reranker-api-key | RERANKER_API_KEY | Reranker Bearer token (optional; required by OpenRouter) | | --reranker-model | RERANKER_MODEL | Reranker model id, e.g. cohere/rerank-4-fast | | --rerank-multiplier | RERANK_MULTIPLIER | Candidate over-fetch factor (default: 3, capped at Seahorse top_k max of 20) |

Reranking

When RERANKER_URL + RERANKER_MODEL are both configured, search over-fetches min(20, top_k × RERANK_MULTIPLIER) candidates from Seahorse, reranks them with the external reranker, and returns the top top_k by relevance score. If the reranker is unreachable, the original ranking is returned instead (search stays available). Rerank status is surfaced in debug_info.rerank.

Tested OpenRouter models (POST https://openrouter.ai/api/v1/rerank):

| Model | Latency* | Price | Notes | |-------|----------|-------|-------| | cohere/rerank-4-fast | ~0.7s | $0.002/search | Balanced | | cohere/rerank-4-pro | ~0.5s | $0.0025/search | Highest confidence scores | | cohere/rerank-v3.5 | ~0.7s | $0.001/search | Cheapest, conservative scoring |

* 8-document Korean query in ad-hoc testing; not a benchmark.

Quick Install (Claude Desktop)

npx @dn-inc/seahorse-mcp-seahorse install \
  --api-url https://YOUR_TABLE_ID.api.seahorse.dnotitia.com \
  --api-key YOUR_API_KEY

This automatically adds the server to your Claude Desktop configuration.

Available Tools

search

Perform hybrid search with automatic embedding generation.

Parameters:

• query (string, required): Natural language search query
• search_mode (string): "dense" | "sparse" | "hybrid" (default: "hybrid")
• top_k (int): Number of results (default: 3, max: 20)
• metadata_filter (string): Filter by metadata content
• filter (string): SQL WHERE clause for advanced filtering
• ef_search (int): HNSW ef_search parameter (default: 150)
• rrf_k (int): RRF k parameter for hybrid fusion (default: 60)

Example:

{
  "query": "machine learning algorithms",
  "search_mode": "hybrid",
  "top_k": 5,
  "metadata_filter": "research-paper"
}

get_adjacent_chunks

Retrieve previous and next chunks for context expansion.

Parameters:

• document_id (string, required): Document identifier from search results
• chunk_sequence (string, required): Chunk sequence number (e.g., "0151")

MCP Client Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "seahorse-hybrid-search": {
      "command": "npx",
      "args": ["-y", "@dn-inc/seahorse-mcp-seahorse"],
      "env": {
        "SEAHORSE_API_URL": "https://YOUR_TABLE_ID.api.seahorse.dnotitia.com",
        "SEAHORSE_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Custom MCP Clients

Point your MCP client to run this command and connect via stdio. No host/port configuration needed.

How It Works

1. Creates .seahorse-mcp-venv in your OS cache directory for isolation
2. Installs minimal Python dependencies (fastmcp, requests, urllib3)
3. Launches seahorse_mcp_hybrid_search.py as a stdio MCP server

API Details

This server uses the Seahorse v2 API:

• Endpoint: POST {api_url}/v2/data/search
• Scan Endpoint: POST {api_url}/v2/data/scan (for adjacent chunks)
• Schema: GET {api_url}/v1/data/schema

Search Request Format

{
  "top_k": 5,
  "search_mode": "hybrid",
  "dense": {
    "column": "dense_vector",
    "text": ["your query here"],
    "parameters": { "ef_search": 150 }
  },
  "sparse": {
    "column": "sparse_vector",
    "text": ["your query here"],
    "parameters": { "k": 1.2, "b": 0.75 }
  },
  "fusion": {
    "type": "rrf",
    "parameters": { "k": 60 }
  },
  "projection": "id, text, metadata"
}

Requirements

• Node.js >= 18
• Python 3.8+

License

MIT