--- title: "Deploy Typesense MCP" description: "Let AI agents query Typesense over MCP" category: "Analytics" url: https://railway.com/deploy/deploy-typesense-mcp-server-for-agents --- # Deploy Typesense MCP Let AI agents query Typesense over MCP **[Deploy Typesense MCP on Railway](https://railway.com/template/deploy-typesense-mcp-server-for-agents)** Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/deploy-typesense-mcp-server-for-agents/manifest.json - **Creator:** onepush - **Category:** Analytics ## Template content ### typesense-railway - **Source:** Shinyduo/typesense-railway - **Public domain:** Yes ## Documentation # Deploy and Host self hosted Typesense MCP (MCP Search for AI Agents) on Railway This Railway template runs a Typesense node behind Caddy. Point a community MCP server like TypesenseKit at the public URL and your AI coding agent can search and read schemas using a scoped key, not the admin key. ## About Hosting Typesense MCP open-source software on Railway (self hosted Typesense template) This template runs Typesense 30 behind Caddy on one Railway service; Caddy listens on PORT 8080 and proxies to 127.0.0.1:8118. Your index stays in the Railway volume at TYPESENSE_DATA_DIR. CORS is off by default. Railway handles TLS, the volume, and restarts, so you skip nginx and certbot. ## Why Deploy Typesense MCP, the Algolia alternative on Railway (Railway Free Trial) Algolia bills per search and per record, so an agent exploring schemas and testing filter_by can run up costs fast. Self-hosting Typesense on Railway flips that: you pay for compute and volume, not per query. The Railway $5 trial is enough to test the agent workflow. Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it. By deploying Typesense MCP on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway. ### Railway vs Other Hosting Providers and VPS for Typesense MCP self hosting Railway removes the reverse-proxy and TLS plumbing other providers leave to you. | Provider | What You Get with Railway | What You Get with the Other Provider | | --- | --- | --- | | DigitalOcean | Public HTTPS domain, Caddy, and managed volume for Typesense data, all in the template. | A droplet; you install Caddy, certs, and backups yourself. | | AWS | Repo build, PORT forwarding, and persistent volume as one service. | EC2 and EBS, but you wire the reverse proxy and health checks. | | Hetzner | Zero-config TLS on the public HTTPS domain your MCP client calls. | Cheap compute, but DNS, certs, and OS updates are on you. | The scoped key flow is identical either way. ## Common Use Cases for hosted Typesense MCP - **Agent-driven debugging**: Claude Code or Cursor asks TypesenseKit to list collections and read schema, then writes valid filter_by or facet_by without guessing. Read-only default keeps it safe. - **Support search on your own docs**: Point the MCP server at your public https domain with a scoped key for documents:search and collections:get, and agent turns natural language into multi-search queries. - **Document inspection for context**: When an agent needs the raw JSON of a record, the MCP document lookup tool fetches it from your self-hosted Typesense. - **Controlled write workflows**: Set TYPESENSEKIT_READ_ONLY=false with a scoped key for documents:create or delete, and let an agent index or clean records while the admin TYPESENSE_API_KEY stays in Railway variables. ## Dependencies for Typesense MCP Docker hosted on Railway The Railway template runs Typesense itself, not an MCP server. The only hard dependency is a reachable Typesense endpoint plus a scoped API key. ### Deployment Dependencies for Managed Typesense MCP Service (Agent Search) Service builds from Shinyduo/typesense-railway: a Typesense 30 image with a small Caddy reverse proxy. Caddy listens on 8080 and forwards to Typesense on 127.0.0.1:8118. CORS is off by default; MCP servers are server-side, so that is fine. ### Implementation Details for Typesense MCP (Using Typesense official docker image) A Typesense 30 image forms the base, but do not set --data-dir /data or --enable-cors manually: the template's Caddy layer and volume variable handle persistence and routing. Never give an agent the admin TYPESENSE_API_KEY; put a scoped key from POST /keys in the MCP config. ## How does Typesense MCP compare against other search engines for AI agents platforms ### Typesense MCP vs Algolia (Algolia Alternative) - **Self-hosting**: Typesense MCP runs on your Railway Typesense with no per-search fees; Algolia is SaaS-only and bills requests plus records. - **Agent safety**: TypesenseKit defaults to read-only and pairs with scoped keys. Algolia wins on polished, vendor-supported tooling. ### Typesense MCP vs Meilisearch (Meilisearch Alternative) - **Scoped permissions**: Typesense keys limit actions and collections, matching the MCP's read-only default; Meilisearch keys are scoped too, and Meilisearch maintains its own MCP server. - **Self-hosted parity**: Both are self-hosted engines, but Typesense's single binary simplifies Railway deployment under agent load. Meilisearch wins on gentle typo handling. ### Typesense MCP vs Elasticsearch (Elasticsearch Alternative) - **Memory footprint**: Typesense is in-memory and sized to the dataset; Elasticsearch needs JVM heap tuning. The MCP just reads schemas and searches. - **Schema inspection**: Agents list collections and fields, then write filter_by and sort_by confidently; Elasticsearch mappings are harder to introspect. Elasticsearch wins for log-scale aggregations. ### Typesense MCP vs Pinecone (Pinecone Alternative) - **Workload fit**: Typesense MCP handles keyword, facet, and hybrid search; Pinecone targets vector similarity. Pick based on semantic recall vs exact filters. - **Cost model**: Self-hosted Typesense has no per-query fee; Pinecone serverless bills reads, writes and storage. Pinecone wins for pure embedding search. ## How to use Typesense MCP (the OSS Agent Search)? 1. On your laptop, run `npx -y @typesensekit/mcp` with `TYPESENSE_URL` set to your Railway public HTTPS domain (Caddy front) and `TYPESENSE_API_KEY` set to a scoped key, not the admin key. Create that key via `POST /keys` with actions `["documents:search","collections:get"]` and limited collections, optionally `expires_at`. 2. Point Claude Code, Cursor, Codex, or Claude Desktop at the stdio MCP server. It is read-only by default; write tools stay hidden unless you set `TYPESENSEKIT_READ_ONLY=false`. Review the community-maintained code before relying on it. 3. Ask the agent to list collections and schema first, then query with `filter_by`, `sort_by`, and `facet_by`, once it can read the schema, it composes those clauses well. ## How to self host Typesense MCP on other VPS Services (Typesense MCP self hosting guide) ### Clone the Repository Typesense has no built-in MCP server, so clone a community bridge like TypesenseKit and review the code. ### Install Dependencies ``` npm install -g @typesensekit/mcp ``` Or run ad hoc: npx -y @typesensekit/mcp. ### Configure Environment Variables First create a scoped key via POST /keys with actions ["documents:search","collections:get"] and a collections whitelist; optionally set expires_at. Never use the admin TYPESENSE_API_KEY. ``` TYPESENSE_URL=https://your-domain TYPESENSE_API_KEY=your-scoped-key # TYPESENSEKIT_READ_ONLY=false only if you need write tools ``` Point TYPESENSE_URL at the public domain; Caddy terminates TLS on 443. ### Start the Typesense MCP Application Run the stdio server on the machine where Claude Code, Cursor, or Codex lives: ``` npx -y @typesensekit/mcp ``` Register it in your MCP client. Agents can read schema and build filter_by, sort_by, facet_by queries. Railway handles the Typesense node, volume, and reverse proxy; only this local bridge moves. ## Official Pricing of Typesense MCP (Typesense MCP pricing) Typesense MCP itself is free: the community TypesenseKit server is MIT-licensed, and there's no license fee for wiring agents to your Railway Typesense. So self-hosting MCP access costs whatever your Typesense service already costs on Railway. ## Typesense MCP cloud vs self hosted comparison (Pricing, features, costs, and more) Typesense Cloud's remote MCP only manages Cloud accounts, so it ignores a Railway deployment. Self-hosting gives you the URL and no per-search billing. ### Monthly cost of self hosting Typesense MCP on Railway Self-hosting on Railway means paying compute plus a volume. Typesense Cloud bills RAM and vCPU by the hour plus bandwidth, so an always-on cluster adds up; check its pricing page for current numbers. For a small agent index, self-hosting usually costs less. ### System Requirements for Hosting Typesense MCP on a VPS Typesense holds the index in RAM, so size memory to dataset plus query overhead. A small collection runs on a modest VPS; larger schemas need a second vCPU for agent filter_by calls. The MCP server runs on your machine, not the VPS. ## Frequently Asked Questions (FAQs) ### Is there an official Typesense MCP server for self-hosted Typesense? No. Typesense doesn't ship an MCP server, and no official one exists yet. Use a community server like TypesenseKit or build your own. ### Can I use the Typesense Cloud MCP endpoint with my Railway deployment? No. The cloud.typesense.org/mcp/v1 endpoint only manages Typesense Cloud accounts. Point your MCP config at the template's public HTTPS domain. ### Where should the Typesense MCP server run? Run it on your developer machine or next to the agent. Set TYPESENSE_URL to the template's public https domain and use a scoped key. ### How do I stop my agent from writing or deleting data through Typesense MCP? Create a scoped key with POST /keys, limiting actions to ["documents:search"] and collections to the agent's needs. TypesenseKit is read-only by default. ### What is the safest key to give Typesense MCP? Never give the admin TYPESENSE_API_KEY. Generate a scoped key with search-only actions, limited collections, and optionally expires_at. ### Can Typesense MCP help my agent write complex filter_by or sort_by queries? Yes. Once the agent reads the schema via collections:get, it can generate filter_by, sort_by, and facet_by parameters. Keep write tools hidden unless needed. ## Similar templates - [Typesense Multilingual](https://railway.com/deploy/deploy-typesense-multilingual-search) — Locale-aware multilingual search with Typesense - [Formbricks | Open-Source Typeform & Qualtrics Alternative](https://railway.com/deploy/formbricks-surveys) — Surveys, NPS and in-app feedback on your own Postgres, Hub and Cube - [Typesense PHP](https://railway.com/deploy/typesense-php) — official PHP client against Railway Open this page in a browser: https://railway.com/deploy/deploy-typesense-mcp-server-for-agents