# @voxell/forge-mcp

An MCP server for **Forge** — Voxell's hosted text-embedding API. It exposes Forge to any
MCP client (Claude, Cursor, Cline, Windsurf, VS Code, …) as two tools:

- **`embed`** — turn text into vectors
- **`list_models`** — list available models and their dimensions

You bring a Forge API key. The server is stateless, and **Voxell does not store the text you
send or the vectors it returns** — only usage metadata (token counts) is recorded, for billing.
It does embeddings only — no storage, no search, no RAG. Those are different products.

## Quick install

One-click install in your editor (then replace `your-key-here` with a real key from
[dash.voxell.ai](https://dash.voxell.ai)):

[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=forge&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB2b3hlbGwvZm9yZ2UtbWNwIl0sImVudiI6eyJGT1JHRV9BUElfS0VZIjoieW91ci1rZXktaGVyZSJ9fQ==)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](vscode:mcp/install?%7B%22name%22%3A%22forge%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40voxell%2Fforge-mcp%22%5D%2C%22env%22%3A%7B%22FORGE_API_KEY%22%3A%22your-key-here%22%7D%7D)

**Claude Code** — one command:

```bash
claude mcp add forge -e FORGE_API_KEY=your-key-here -- npx -y @voxell/forge-mcp
```

Any other client (Claude Desktop, Cline, Windsurf, Zed, …) uses the standard `mcpServers`
block — see [Use it](#use-it) below.

## Why Forge

- **Quality you can dial.** Three tiers: `turbo` (1024d, fast, the default), `pro` (2560d) and
  `ultra` (4096d, highest quality). Pick your point on the quality and cost curve.
- **Benchmark-leading.** Voxell's Ingot-8B-R3 ranks #1 for English on the public MTEB leaderboard
  (English v2), with a 75.98 mean task score across 41 tasks: the top usable English embedding
  model. See the [model card](https://huggingface.co/JCorners/Ingot-8B-R3).
- **Measured on public documents.** Voxell's retrieval pipeline, built on Forge, is measured on
  four public corpora (7,817 documents, 980,885 passages). On 800 model-written questions, which
  are easier than a test set written by people, the first result answers the question for 83%.
  Method and limits: [Measured retrieval](#measured-retrieval).
- **Matryoshka (MRL).** Set `dim` to truncate (re-normalized) for ~4× smaller, cheaper vectors.
- **Low latency** (Go + CUDA engine), **zero-trust** (per-key auth; mTLS available), and **free to
  start** (`turbo` is free forever, no card: [dash.voxell.ai](https://dash.voxell.ai); more at
  [voxell.ai/forge](https://voxell.ai/forge)).

## Measured retrieval

This server returns vectors only. Voxell also runs a retrieval pipeline built on Forge, and
publishes what it measures on documents anyone can read.

Four public corpora, 7,817 documents and 980,885 passages in total, 800 questions (200 per
corpus), measured 2026-10-05:

| corpus | documents | first result answers the question | one of the top three answers it |
|--------|-----------|-----------------------------------|---------------------------------|
| SEC filings | 2,010 | 91% | 95% |
| USPTO patents | 4,008 | 86.5% | 91.5% |
| NASA technical reports | 1,210 | 67% | 78% |
| arXiv technical papers | 589 | 86.5% | 96% |
| all four | 7,817 | 83% | 90% |

The right document is in the top ten for 95% of the questions.

Read these numbers for what they are. The questions were written by a model from the documents
and judged against the passage text, which is easier than a test set written by people. The
numbers describe what this pipeline does on these corpora. They are not a comparison with any
other vendor, and they are not what the `embed` tool does on its own: the pipeline adds the steps
the receipts list, such as a cross-encoder reranker, a one-line document identity in every
passage, and routing to the documents a question names. Each receipt is published with a fixed
sample of its questions, misses included: [voxell.ai/retrieval](https://voxell.ai/retrieval/).

## What you can do with it

- **Add semantic search** — embed your documents with `input_type: "document"` and each query
  with `input_type: "query"`, then rank by cosine similarity.
- **Build RAG** — embed a knowledge base, store the vectors, and retrieve the closest chunks to
  ground an LLM.
- **Find similar or duplicate text** — embed two texts and compare their vectors.
- **Cluster or classify** — embed a batch, then cluster or train a classifier on the vectors.
- **Shrink vector storage** — set `dim` to truncate (Matryoshka) and trade a little accuracy
  for smaller, cheaper vectors.
- **Straight from your editor** — ask your AI agent (Cursor, Claude, …) to embed a snippet, a
  batch, or a file via the `embed` tool — no separate script.

## Requirements

- Node.js ≥ 18 (tested on 20)
- A Forge API key — create one at https://dash.voxell.ai. `turbo` is free forever, no card.

## Use it

Most MCP clients run it on demand with `npx`. Add this to your client's MCP config:

```json
{
  "mcpServers": {
    "forge": {
      "command": "npx",
      "args": ["-y", "@voxell/forge-mcp"],
      "env": { "FORGE_API_KEY": "your-key-here" }
    }
  }
}
```

(Cursor, Claude Desktop, Cline, Windsurf, and VS Code all use this `mcpServers` shape.)

## Tools

### `embed`

| arg | type | default | notes |
|-----|------|---------|-------|
| `input` | string or string[] | — | text(s) to embed (required) |
| `model` | string | `turbo` | `turbo` (1024-d), `pro` (2560-d), `ultra` (4096-d) |
| `dim` | number | model default | truncate to N dimensions (Matryoshka) — works on every model |
| `input_type` | `"query"` \| `"document"` | `document` | use `query` for search queries |

Returns the vectors plus the model, dimension, and token count.

Default is `turbo` — the one you probably want. `pro`/`ultra` trade size and speed for more
dimensions.

### `list_models`

Lists the available models and their dimensions.

## Configuration

| env | required | default |
|-----|----------|---------|
| `FORGE_API_KEY` | yes | — |
| `FORGE_BASE_URL` | no | `https://api.voxell.ai` |

## Beyond MCP: OpenAI-compatible API

Forge speaks the **OpenAI embeddings API**. Point any OpenAI client at Forge — **no code change**,
and your existing vector dimensions are preserved:

```python
from openai import OpenAI

client = OpenAI(base_url="https://api.voxell.ai/v1", api_key="your-forge-key")
# the exact call you already make — now on a higher-ranked engine:
client.embeddings.create(model="text-embedding-3-large", input=["hello world"])  # -> 3072-d
```

Your OpenAI model names map to a **matching-dimension** Forge tier (`text-embedding-3-small`/
`ada-002` → 1536-d, `text-embedding-3-large` → 3072-d), so existing vector stores slot in
unchanged. Or address Forge tiers directly — `turbo` | `pro` | `ultra`. Also supports `dimensions`
(Matryoshka, re-normalized) and `encoding_format: "base64"`.

**It's an upgrade on every path.** Forge's *smallest* tier (`turbo`) outranks OpenAI's
*largest* embedding model (`text-embedding-3-large`) on MTEB, so there's no drop-in that lands
worse. And Voxell's Ingot-8B-R3 ranks #1 for English on the public MTEB leaderboard: a different
league.

**Why re-embedding onto Forge is worth it.** Embedding is a one-way door: whatever an encoder
discards at write time is gone — no reranker, longer prompt, or bigger LLM downstream reconstructs
what the vectors never captured. The model you embed with sets the ceiling on everything above it.
Re-embed once onto a higher-ranked engine and that ceiling rises — permanently.

## License

MIT © Voxell, Inc.