Connect your AI client

Before you connect

You need Node.js 22.11 or newer, your Typesense cluster URL, and an API key. Use a search-only or otherwise scoped key whenever possible.

Claude Desktop

Add the server to Claude Desktop's MCP configuration, replace both placeholder values, save, and restart Claude Desktop.

{
  "mcpServers": {
    "typesensekit": {
      "command": "npx",
      "args": ["-y", "@typesensekit/mcp"],
      "env": {
        "TYPESENSE_URL": "https://your-cluster.typesense.net",
        "TYPESENSE_API_KEY": "your-scoped-api-key"
      }
    }
  }
}

You can generate the same configuration from the CLI.

tsk skills claude-desktop

Claude Code

Add the stdio server with Claude Code's MCP command, then make the Typesense variables available in your shell or MCP environment.

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

TypesenseKit can print this command for you with tsk skills claude-code. Run claude mcp list to confirm the server is registered.

For scopes, inline environment configuration, verification prompts, and troubleshooting, follow the complete Claude Code and Typesense MCP guide.

Codex

Codex CLI, the IDE extension, and the ChatGPT desktop app share MCP configuration. Add this to ~/.codex/config.toml, or use .codex/config.toml inside a trusted project.

[mcp_servers.typesensekit]
command = "npx"
args = ["-y", "@typesensekit/mcp"]
env_vars = ["TYPESENSE_URL", "TYPESENSE_API_KEY"]
default_tools_approval_mode = "writes"

Export the variables before starting Codex. The writes approval mode complements TypesenseKit's MCP annotations if you later enable write tools.

export TYPESENSE_URL=https://your-cluster.typesense.net
export TYPESENSE_API_KEY=your-scoped-api-key
codex mcp list

See the official Codex MCP guide for configuration scope and additional tool policies.

Cursor

Create .cursor/mcp.json in a project for project-scoped access, or add the same server through Cursor's MCP settings. Replace the placeholder connection values.

{
  "mcpServers": {
    "typesensekit": {
      "command": "npx",
      "args": ["-y", "@typesensekit/mcp"],
      "env": {
        "TYPESENSE_URL": "https://your-cluster.typesense.net",
        "TYPESENSE_API_KEY": "your-scoped-api-key"
      }
    }
  }
}

Restart or refresh Cursor's MCP servers after changing the file. The server should appear as typesensekit with read-only tools.

Any stdio-compatible MCP client

Use the generic JSON configuration when a client accepts the common mcpServers shape.

{
  "mcpServers": {
    "typesensekit": {
      "command": "npx",
      "args": ["-y", "@typesensekit/mcp"],
      "env": {
        "TYPESENSE_URL": "https://your-cluster.typesense.net",
        "TYPESENSE_API_KEY": "your-scoped-api-key"
      }
    }
  }
}

Or generate it locally:

tsk skills mcp

If your client uses a different configuration envelope, preserve the command, arguments, and environment values shown above.

Verify the connection

1. Restart or refresh the client after saving the configuration.
2. Inspect its MCP server list and confirm TypesenseKit connects without an initialization error.
3. Ask the client to list Typesense collections or check cluster health.
4. Confirm write and delete tools are absent in the default mode.

List my Typesense collections and summarize their document counts.
Do not modify the cluster.

If startup fails, run the package directly in a terminal with the same environment first. That separates Node/package issues from client configuration issues.