# Mcp Registry Search

> Semantic search ETL pipeline for the MCP server registry. Exposed as both FastAPI and MCP servers

- **Type:** MCP server
- **Install:** `agentstack add mcp-lastmile-ai-mcp-registry-search`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [lastmile-ai](https://agentstack.voostack.com/s/lastmile-ai)
- **Installs:** 0
- **Category:** [Data & Analytics](https://agentstack.voostack.com/c/data-and-analytics)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [lastmile-ai](https://github.com/lastmile-ai)
- **Source:** https://github.com/lastmile-ai/mcp-registry-search
- **Website:** https://mcp-registry-search.vercel.app

## Install

```sh
agentstack add mcp-lastmile-ai-mcp-registry-search
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# MCP Registry Search

Semantic search API for MCP servers using the official Model Context Protocol registry.

Use as:
* **REST API (search)**: https://mcp-registry-search.vercel.app/search?q=kubernetes&limit=2
* **REST API (list)**: https://mcp-registry-search.vercel.app/servers?limit=10&offset=0
* **MCP Server (SSE)**: https://mcp-registry-search.vercel.app/api/sse

Cron job reindexes the entire registry every night.

Built with:
* [mcp-agent cloud](https://mcp-agent.com/)
* Supabase
* Vercel

## Usage

### Search REST API

Query the registry using the `/search` endpoint:

**Endpoint:** https://mcp-registry-search.vercel.app/search?q=kubernetes&limit=2

**Example:**
```bash
curl "https://mcp-registry-search.vercel.app/search?q=kubernetes&limit=2"
```

**Example Response:**
```json
{
  "results": [
    {
      "id": 259,
      "name": "io.github.vfarcic/dot-ai",
      "description": "AI-powered development platform for Kubernetes deployments and intelligent automation",
      "version": "0.101.0",
      "repository": {
        "url": "https://github.com/vfarcic/dot-ai",
        "source": "github"
      },
      "packages": [
        {
          "version": "0.101.0",
          "transport": {
            "type": "stdio"
          },
          "identifier": "@vfarcic/dot-ai",
          "registryType": "npm"
        }
      ],
      "remotes": [],
      "similarity_score": 0.606411385574579
    },
    {
      "id": 272,
      "name": "io.github.containers/kubernetes-mcp-server",
      "description": "An MCP server that provides [describe what your server does]",
      "version": "1.0.0",
      "repository": {
        "url": "https://github.com/containers/kubernetes-mcp-server",
        "source": "github"
      },
      "packages": [],
      "remotes": [],
      "similarity_score": 0.451448836663574
    }
  ],
  "query": "kubernetes",
  "limit": 2,
  "count": 2
}
```

**Query Parameters:**
- `q` (required): Search query string
- `limit` (optional): Maximum number of results (default: 10)
- `full_text_weight` (optional): Weight for full-text search (default: 1.0)
- `semantic_weight` (optional): Weight for semantic search (default: 1.0)

### List Servers API

List all servers with pagination using the `/servers` endpoint:

**Endpoint:** https://mcp-registry-search.vercel.app/servers?limit=10&offset=0

**Example:**
```bash
curl "https://mcp-registry-search.vercel.app/servers?limit=5"
```

**Query Parameters:**
- `limit` (optional): Maximum number of results (default: 100)
- `offset` (optional): Number of results to skip (default: 0)

### MCP Server

Connect to the MCP server via SSE for direct integration with MCP clients:

**Endpoint:** https://mcp-registry-search.vercel.app/api/sse

**Available Tools:**
- `search_mcp_servers(query, limit, full_text_weight, semantic_weight)` - Search servers using hybrid search
- `list_mcp_servers(limit, offset)` - List all servers with pagination

**Add to your MCP client config:**
```json
{
  "mcpServers": {
    "registry-search": {
      "url": "https://mcp-registry-search.vercel.app/api/sse",
      "transport": {
        "type": "sse"
      }
    }
  }
}
```

## Features

- 🔍 **Hybrid search** combining lexical (PostgreSQL full-text) and semantic (pgvector) search
- 🚀 **Fast vector similarity** using OpenAI embeddings + Supabase pgvector
- 📊 **Ranked results** using weighted scoring
- 🔄 **Automatic ETL pipeline** to fetch and index MCP servers
- 🌐 **FastAPI REST API** for web access
- 🔌 **FastMCP server** for MCP client integration
- ☁️ **Deployable to Vercel** (FastAPI) and any MCP-compatible host (FastMCP)

## Architecture

```
┌─────────────────┐
│  MCP Registry   │
│   (Source API)  │
└────────┬────────┘
         │
         │ ETL Pipeline
         ↓
┌─────────────────┐
│    Supabase     │
│  (PostgreSQL +  │
│    pgvector)    │
└────────┬────────┘
         │
         │ Search Query
         ↓
┌─────────────────┬─────────────────┐
│   FastAPI REST  │mcp-agent Server │
│      (Web)      │   (MCP Clients) │
└─────────────────┴─────────────────┘
```

## Development

### 1. Install dependencies

```bash
uv sync
```

### 2. Set up Supabase

1. Create a [Supabase account](https://supabase.com)
2. Create a new project
3. Run the SQL in `schema.sql` in the Supabase SQL editor
4. Get your project URL and anon key from Settings > API

### 3. Configure environment variables

```bash
cp .env.example .env
```

Edit `.env` and add:
- `OPENAI_API_KEY`: Your OpenAI API key
- `SUPABASE_URL`: Your Supabase project URL
- `SUPABASE_KEY`: Your Supabase anon key

### 4. Run ETL to fetch and index servers

```bash
uv run etl.py
```

This will:
1. Fetch all servers from the MCP registry
2. Filter to active servers (latest versions only)
3. Generate embeddings using OpenAI
4. Store in Supabase with vector indices

### 5. Start the servers

**FastAPI (REST API):**
```bash
uvicorn api:app --reload
```

API available at `http://localhost:8000`
- Docs: `http://localhost:8000/docs`

**FastMCP (MCP Server):**
```bash
uv run main.py
```

## API Usage

### REST API

**Search servers:**
```bash
curl "http://localhost:8000/search?q=kubernetes&limit=5"
```

**List all servers:**
```bash
curl "http://localhost:8000/servers?limit=100&offset=0"
```

**Health check:**
```bash
curl "http://localhost:8000/health"
```

### MCP Server

The FastMCP server provides:

**Tools:**
- `search_mcp_servers(query, limit, full_text_weight, semantic_weight)` - Search servers
- `list_mcp_servers(limit, offset)` - List all servers

**Resources:**
- `mcp-registry://search/{query}` - Search results as formatted text

**Prompts:**
- `find_mcp_server(task)` - Prompt template to find servers for a task

**Add to your MCP client config:**
```json
{
  "mcpServers": {
    "registry-search": {
      "command": "uv",
      "args": ["run", "main.py"],
      "cwd": "/path/to/mcp-registry-search",
      "env": {
        "OPENAI_API_KEY": "your-key",
        "SUPABASE_URL": "your-url",
        "SUPABASE_KEY": "your-key"
      }
    }
  }
}
```

## Deployment

### Vercel (FastAPI)

1. Install Vercel CLI:
```bash
npm i -g vercel
```

2. Add environment variables to Vercel:
```bash
vercel env add OPENAI_API_KEY
vercel env add SUPABASE_URL
vercel env add SUPABASE_KEY
vercel env add CRON_SECRET  # Random secret to protect cron endpoint
```

3. Deploy:
```bash
vercel
```

**Automatic ETL Updates:**
The project includes a Vercel Cron job that runs nightly at midnight (UTC) to refresh the server index. The cron job calls `/api/cron/etl` which is protected by the `CRON_SECRET` environment variable.

### Public SSE Proxy (Edge)

Expose an authenticated upstream SSE endpoint publicly by proxying through a Vercel Edge Function that injects the bearer token and streams responses.

1) Configure env vars (in Vercel):
```bash
vercel env add UPSTREAM_SSE_URL   # e.g. https:///sse
vercel env add UPSTREAM_SSE_TOKEN # bearer token for upstream
```

Alternative names supported for the token: `LM_API_KEY` or `LM_API_TOKEN`.

2) Endpoint path
- The SSE proxy is available at `/api/sse` (see `api/sse.ts`).
- The MCP messages proxy is available at `/api/messages` (see `api/messages.ts`).
- Rewrites expose root paths: `/sse` → `/api/sse`, `/messages` → `/api/messages` for MCP clients that expect root-level endpoints.

3) CORS and streaming
- CORS: `Access-Control-Allow-Origin: *`
- Streaming: Edge Runtime streams SSE by default; cache disabled.

4) Example usage
```bash
curl -N https://.vercel.app/api/sse
# or using the root rewrite
curl -N https://.vercel.app/sse
```

5) Custom upstream per deployment (optional)
- Override with `UPSTREAM_SSE_URL` in env without changing code.
- Messages upstream auto-derives from the SSE URL, or set `UPSTREAM_MESSAGES_URL` explicitly if needed.

### mcp-agent Server
We use [mcp-agent cloud](https://mcp-agent.com) to deploy and host the MCP server. Under the covers, it's a FastMCP server (see [main.py](./main.py)).

To do so yourself, you can run:
* uv run mcp-agent login
* uv run mcp-agent deploy

## Manual ETL Updates

To manually refresh the server index:

**Locally:**
```bash
uv run etl.py
# or
make etl
```

**On Vercel (trigger cron endpoint):**
```bash
curl -X GET https://your-project.vercel.app/api/cron/etl \
  -H "Authorization: Bearer YOUR_CRON_SECRET"
```

The automatic nightly cron job handles updates, but you can manually trigger it anytime.

## Development

**Project structure:**
```
registry/
├── api.py              # FastAPI REST API (hosted on Vercel)
├── main.py             # MCP server (hosted on mcp-agent cloud)
├── search.py           # Search engine
├── etl.py              # ETL pipeline
├── schema.sql          # Supabase schema
├── pyproject.toml      # Dependencies
├── vercel.json         # Vercel config
└── README.md           # This file
```

## License

Apache 2.0

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [lastmile-ai](https://github.com/lastmile-ai)
- **Source:** [lastmile-ai/mcp-registry-search](https://github.com/lastmile-ai/mcp-registry-search)
- **License:** Apache-2.0
- **Homepage:** https://mcp-registry-search.vercel.app

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-lastmile-ai-mcp-registry-search
- Seller: https://agentstack.voostack.com/s/lastmile-ai
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.