Safe agent access

Give an AI agent read-only Typesense access

Use TypesenseKit's read-only MCP default with a scoped Typesense API key, verify the exposed tools, and enable writes only for controlled workflows.

Use two independent safety boundaries

Agent access should be limited twice: TypesenseKit decides which tools the MCP client can see, and the Typesense API key decides which requests the cluster will accept.

  1. MCP tool boundary: read-only mode hides write, delete, key-management, and raw API operations.
  2. Typesense authorization boundary: a scoped key restricts actions and collections even if the MCP configuration changes.

Use both. A hidden tool is not a substitute for cluster authorization, and a scoped key does not stop an agent from attempting irrelevant operations.

Start the MCP server read-only

Read-only mode is the default. Leave TYPESENSEKIT_READ_ONLY unset or set it explicitly to true.

shell
TYPESENSEKIT_READ_ONLY=true \
TYPESENSE_URL=https://your-cluster.typesense.net \
TYPESENSE_API_KEY=your-scoped-api-key \
pnpm dlx @typesensekit/mcp

This mode includes search, document reads and exports, collection schemas and metadata, configuration reads, system health, metrics, stats, and other non-mutating operations from the 95-operation registry.

Create a narrowly scoped Typesense key

Start from the exact collections and actions the agent needs. For a search-only assistant, create a key limited to document search on the relevant collection.

shell
tsk keys.create --input '{"description":"Read-only product search agent","actions":["documents:search"],"collections":["products"]}'

Store the generated key in the MCP client's environment or secret manager. Do not put it in a repository, prompt, shell history, or shared screenshot.

Broaden deliberately. Schema inspection, document retrieval, exports, and system metrics may require additional Typesense actions. Add only the actions the workflow has demonstrated it needs.

Verify the effective boundary

TypesenseKit exposes two resources that make the current operation surface inspectable:

  • typesensekit://operations — operations active in the current MCP mode.
  • typesensekit://read-only-tools — tool names included in the safe default.

After connecting the server, verify all three layers:

  1. The MCP client lists TypesenseKit as connected.
  2. Write, delete, key-management, and api.call tools are absent.
  3. The scoped API key rejects requests outside its allowed actions and collections.
Boundary check prompt
List the Typesense tools available to you.
Confirm whether any tool can create, update, delete, manage keys, or call a raw API endpoint.
Do not execute any cluster operation.

Treat read access as sensitive

Read-only does not mean harmless. Document retrieval and exports can expose customer, catalog, analytics, or internal operational data. Search queries may also reveal information an end user should not see.

  • Use separate keys for separate agents and environments.
  • Restrict collections as well as actions.
  • Avoid document export unless the workflow requires bulk access.
  • Keep production and development configurations separate.
  • Review MCP host logs and tool approvals where available.

Enable writes only for a controlled workflow

Set TYPESENSEKIT_READ_ONLY=false only after defining the required mutations, approval behavior, rollback plan, and scoped Typesense key.

shell
TYPESENSEKIT_READ_ONLY=false \
TYPESENSE_URL=https://your-cluster.typesense.net \
TYPESENSE_API_KEY=your-workflow-specific-key \
pnpm dlx @typesensekit/mcp

Full mode exposes document writes, destructive operations, key management, and the raw api.call escape hatch. The MCP host controls user approvals; TypesenseKit provides safety annotations and keeps the default surface narrow.

Before production use, read the complete MCP security guidance.