MCP guide

Typesense MCP setup and security guide

Install the Typesense MCP server, connect AI clients, use read-only defaults, and securely expose Typesense operations to agents.

Start the stdio server

Looking for the product overview? Start with the TypesenseKit Typesense MCP server, then use this guide for transport, resources, and production security.

Compatible MCP clients can launch the package directly from npm. Provide the Typesense URL and a suitably scoped API key in the server environment.

shell
TYPESENSE_URL=http://localhost:8108 \
TYPESENSE_API_KEY=xyz \
pnpm dlx @typesensekit/mcp

The process communicates over stdio, so your client should own its lifecycle and send MCP messages through standard input and output.

Read-only is the default

TypesenseKit exposes search, document reads, collection metadata, configuration reads, and system status operations by default. Write, delete, key-management, and raw API tools stay hidden.

No flag is required. An unset TYPESENSEKIT_READ_ONLY value is interpreted as read-only.

This is the recommended mode for assistant search, support investigation, relevance debugging, and cluster inspection.

Use the read-only Typesense agent access guide to combine the MCP tool boundary with a scoped Typesense API key and verify the effective permissions.

Opt in to full access

Set TYPESENSEKIT_READ_ONLY=false only when an agent must mutate data or administer the cluster.

shell
TYPESENSEKIT_READ_ONLY=false \
TYPESENSE_URL=http://localhost:8108 \
TYPESENSE_API_KEY=xyz \
pnpm dlx @typesensekit/mcp

Full mode includes document writes, destructive operations, key management, and api.call. The MCP host—not the server—decides how and when to ask the user for tool approval.

Use MCP resources

In addition to tools, the server exposes resources that help clients inspect the current operation surface and fetch Typesense records directly.

  • typesensekit://operations — manifest for operations active in the current mode.
  • typesensekit://read-only-tools — names available in the safe default mode.
  • typesense://collections/{collection}/schema — collection schema.
  • typesense://collections/{collection}/documents/{id} — one document.

Run Streamable HTTP or Docker

For a stateless HTTP transport, use the package's dedicated binary.

shell
TYPESENSE_URL=http://localhost:8108 \
TYPESENSE_API_KEY=xyz \
pnpm dlx --package @typesensekit/mcp typesensekit-mcp-http

The repository also includes a production-oriented Dockerfile and deployment guidance. Follow the HTTP and Docker guide for health checks, origins, host/port configuration, and container examples.

Find TypesenseKit in the MCP Registry

The package includes verified registry metadata under io.github.akshitkrnagpal/typesensekit. The registry entry points clients to the public npm package and its required environment variables.

shell
curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.akshitkrnagpal/typesensekit"

Production safety checklist

  • Keep read-only mode enabled for assistant-facing deployments.
  • Use a scoped Typesense key and separate keys for separate workloads.
  • Treat document exports as sensitive even though they are read-only.
  • Do not expose the HTTP transport publicly without authentication and network controls.
  • Keep api.call unavailable unless the workflow genuinely needs unwrapped endpoints.
  • Set explicit connection timeouts and monitor tool calls in the MCP host.

Read the full MCP security and operations guide before enabling production access.