# similarity-search-api-sdk [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/nexus-mcp-infra/similarity-search-api-sdk  
**GitHub Stars:** 0  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/similarity-search-api-sdk

## Description
Stateless NMI + cosine fusion with entropy-driven alpha calibration

## Claude Desktop Quick Installation
Remote MCP endpoint (confidence: high). Install path detected from listing signals. Add as a URL/SSE server in your client:

```json
"mcpServers": {
  "similarity-search-api-sdk": {
    "url": "https://similarity-search-api-production.up.railway.app"
  }
}
```

## Documentation & README

# Similarity Search API

Stateless similarity search over pre-computed vectors — NMI (normalized mutual information) + cosine fusion, with an entropy-calibrated blending weight computed per request. No vector database, no index to maintain, no infrastructure to run.

Available both as a plain HTTP API and as an MCP server (5 tools) for AI agents.

---

## Important: this operates on vectors, not raw text

This API does **not** embed text for you. `query` and `corpus` entries are pre-computed numeric vectors (e.g. from your own embedding model). If you need text-to-vector embedding first, run that upstream and pass the resulting vectors here.

---

## Base URL
https://similarity-search-api-production.up.railway.app

## Authentication

<!-- PATCH sdk_x402_only_auth_regrounding -->
The 3 business endpoints (`/similarity/search`, `/similarity/calibrate-alpha/v1`,
`/similarity/batch-score`) require **no API key** -- only a valid x402 payment
(see "Pricing" below). The `X-API-Key` gate was dropped from these routes
2026-08-25; Stripe metered billing explicitly excludes them too, so passing a
key does nothing on these 3 routes today. The deprecated, unpriced
`/similarity/calibrate-alpha` (no `/v1` suffix) still requires `X-API-Key` and
always 501s regardless.

`/health` requires no authentication.

## Pricing

Two ways to pay, same endpoints:

- **x402 (pay-per-call, USDC on Base)** — currently on **Base Sepolia testnet**, $0.01/call, no account or API key required beyond the x402 payment flow itself. A request without payment gets `402 Payment Required` with the payment details in the `payment-required` response header.
- **Stripe (metered billing)** — for callers provisioned with an API key and a Stripe customer on the account.

---

## Endpoints

### `POST /similarity/search`
Rank a corpus against a query vector using the composite score.

```json
{
  "query": { "id": "q1", "vector": [0.12, -0.4, 0.91, "..."] },
  "corpus": [
    { "id": "doc1", "vector": [0.10, -0.35, 0.88, "..."] },
    { "id": "doc2", "vector": [0.55, 0.02, -0.14, "..."] }
  ],
  "top_k": 10,
  "nmi_bins": 10,
  "alpha_override": null
}
```

All vectors in `query` and `corpus` must share the same dimensionality (2-4096 dims). `top_k` up to 1000. `alpha_override` (optional) pins the cosine/NMI blend weight instead of calibrating it from corpus entropy.

Response:
```json
{
  "results": [
    { "id": "doc1", "composite_score": 0.91, "cosine_similarity": 0.89, "nmi_score": 0.94, "rank": 1 }
  ],
  "calibrated_alpha": 0.73,
  "corpus_entropy": 3.85,
  "query_id": "q1",
  "corpus_size": 2,
  "latency_ms": 43,
  "request_fingerprint": "..."
}
```

### `POST /similarity/calibrate-alpha/v1`
Compute the entropy-calibrated alpha for a corpus without running a full search - useful for inspecting/debugging calibration behavior before committing to a search call.

### `POST /similarity/batch-score`
Score up to 10,000 `(vector_a, vector_b)` pairs with a fixed `alpha` - no corpus/entropy overhead.

```json
{
  "pairs": [[[0.1, 0.2], [0.15, 0.19]]],
  "alpha": 0.5,
  "nmi_bins": 10
}
```

### `GET /health`
Liveness probe. No auth required. Not billed (excluded from both Stripe and x402).

> Note: `POST /similarity/calibrate-alpha` (without `/v1`) is a deprecated alias kept for backward compatibility - use `/similarity/calibrate-alpha/v1`.

---

## MCP tools

Connect an MCP-compatible client (Claude, Cursor, etc.) to the streamable HTTP endpoint at:
https://similarity-search-api-production.up.railway.app/mcp

Exposes 5 tools: `rank_items_by_nmi_cosine_fusion`, `estimate_corpus_entropy_profile`, `score_pair_nmi_cosine`, `find_outlier_vectors_by_nmi_deficit`, `calibrate_alpha_from_query_entropy`.

---

## The scoring method
composite_score = alpha * cosine(query, doc) + (1 - alpha) * NMI_normalized(query, doc)

`alpha` is calibrated per-request from the Shannon entropy of the submitted corpus (unless you pass `alpha_override`) - high-entropy (dispersed) corpora lean toward cosine; low-entropy (dense/narrow) corpora lean toward NMI, which captures statistical dependence that cosine's geometric angle misses.

---

## Limits

- Corpus size: up to 500,000 items per request
- Vector dimensionality: 2-4,096
- `batch-score` pairs: up to 10,000 per request