Connect Claude Code to Typesense with MCP

What you need

TypesenseKit gives Claude Code access to the same 95 typed Typesense operations available in the CLI. The MCP server is read-only by default, so Claude starts with search, document reads, schemas, collection metadata, configuration reads, and system status tools.

Node.js 22.11 or newer.
Claude Code installed and signed in.
A reachable Typesense cluster URL.
A narrowly scoped Typesense API key.

Keep the safe default. Do not set TYPESENSEKIT_READ_ONLY=false for search, inspection, support, or relevance-debugging workflows.

Add TypesenseKit to Claude Code

Run the following command from the project where you want Claude Code to use Typesense. Claude Code stores a local-scoped server by default.

claude mcp add --transport stdio \
  --env TYPESENSE_URL=https://your-cluster.typesense.net \
  --env TYPESENSE_API_KEY=your-scoped-api-key \
  typesensekit -- npx -y @typesensekit/mcp

All Claude Code options come before the server name. The double dash separates Claude Code's configuration from the command used to launch TypesenseKit.

If you already use the TypesenseKit CLI, it can print the base command:

tsk skills claude-code

Choose where the configuration lives

The default local scope is private to you and only loads in the current project. Use it for production credentials and experiments.

Use --scope user when the same server should be available across your projects. Use --scope project only when the shared .mcp.json configuration contains environment-variable references rather than committed secrets.

claude mcp add --transport stdio --scope user \
  --env TYPESENSE_URL=https://your-cluster.typesense.net \
  --env TYPESENSE_API_KEY=your-scoped-api-key \
  typesensekit -- npx -y @typesensekit/mcp

Never commit an admin key. Project-scoped MCP configuration is designed for version control, so keep credentials in each developer's environment or secret manager.

Verify the MCP connection

List the configured servers, inspect TypesenseKit, then open Claude Code's MCP panel.

claude mcp list
claude mcp get typesensekit

# Inside Claude Code
/mcp

The server should connect successfully and expose read-only tools. Ask Claude to list collections, then confirm that write, delete, key-management, and raw API tools are absent.

Try read-only Typesense prompts

List my Typesense collections and summarize their document counts.

Inspect the products collection schema. Explain which fields are searchable, facetable, and sortable.

Search products for "oak chair" and summarize the strongest matches. Do not modify the cluster.

Check cluster health and highlight anything that needs investigation.

Tool names match the CLI operation registry, including collections.list, collections.retrieve, documents.search, and health.

Troubleshoot startup and permissions

Server does not connect

Run the package directly with the same environment. If this fails, fix the Node, npm, URL, or credential issue before retrying Claude Code.

TYPESENSE_URL=https://your-cluster.typesense.net \
TYPESENSE_API_KEY=your-scoped-api-key \
npx -y @typesensekit/mcp

Claude can connect but a request is denied

The Typesense API key still controls what the server may read. Expand the key only for the required collection and action; do not replace it with a broad admin key by default.

Write tools are missing

That is expected in the default mode. Read the read-only agent access guide before enabling mutations.

For current Claude Code MCP command syntax and scope behavior, see the official Claude Code MCP documentation.