@kovamind/mcp-server

MCP server for Kova Mind — use AI memory in Claude Desktop, Cursor, Windsurf, VS Code, and any MCP-compatible client.

Quick setup

Setup wizard (recommended)

npx @kovamind/mcp-server setup

The wizard health-checks the API, detects your installed MCP clients — Claude Code, Claude Desktop, Cursor, Windsurf, Cline, Antigravity, Gemini CLI — and writes the kovamind server entry into each one. Add --dry-run (or --print) to see exactly what would be written (API key masked) without touching any config.

Prefer manual configuration? Use the per-client snippets below.

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "kovamind": {
      "command": "npx",
      "args": ["-y", "@kovamind/mcp-server"],
      "env": {
        "KOVAMIND_API_KEY": "km_live_xxx",
        "KOVAMIND_USER_ID": "my-user"
      }
    }
  }
}

Cursor

Add to your Cursor MCP settings:

{
  "mcpServers": {
    "kovamind": {
      "command": "npx",
      "args": ["-y", "@kovamind/mcp-server"],
      "env": {
        "KOVAMIND_API_KEY": "km_live_xxx",
        "KOVAMIND_USER_ID": "my-user"
      }
    }
  }
}

VS Code

Add to .vscode/mcp.json:

{
  "servers": {
    "kovamind": {
      "command": "npx",
      "args": ["-y", "@kovamind/mcp-server"],
      "env": {
        "KOVAMIND_API_KEY": "km_live_xxx",
        "KOVAMIND_USER_ID": "my-user"
      }
    }
  }
}

Windsurf

Add to your Windsurf MCP config:

{
  "mcpServers": {
    "kovamind": {
      "command": "npx",
      "args": ["-y", "@kovamind/mcp-server"],
      "env": {
        "KOVAMIND_API_KEY": "km_live_xxx",
        "KOVAMIND_USER_ID": "my-user"
      }
    }
  }
}

Related MCP server: SharedMemory MCP Server

Environment variables

Available tools

Memory

Vault (zero-exposure credentials)

Credential values never reach the AI. Store a credential once, get back an opaque handle, then ask the AI to act with that handle — the value flows through a secure side channel.

vault_execute output is additionally scrubbed: if the executed request's response echoes a credential (echo endpoints, request dumps), it comes back as [REDACTED <type>], never the raw value.

Credential guard

A memory product that silently stores a pasted API key is a security failure. memory_extract runs 17 client-side detection patterns (OpenAI, Anthropic, Stripe, GitHub, AWS, Slack, Google, npm, Kova Mind keys, Bearer tokens, private keys, SSNs, inline passwords, generic hex secrets) on the conversation before anything reaches the API. On a match, the tool refuses and points you at vault_store, which encrypts the secret and returns an opaque handle instead.

Troubleshooting

403 — API key is bound to a different agent identity

A Kova Mind API key can be bound server-side to a single user_id (agent identity). If a request's user_id does not match the identity the key is bound to, the API returns:

HTTP 403 {"detail":"API key is bound to a different agent identity"}

This surfaces in any tool that takes a user_id (e.g. memory_extract, memory_recall, memory_surprise) as a ... failed: API error 403: ... message.

What to do:

• Make sure the user_id you pass (or the KOVAMIND_USER_ID env var) matches the identity the key was issued for.

• Unbound keys are unaffected — they pass the client-supplied user_id through unchanged, so a single unbound key can serve multiple users.

• If you need one key per agent, bind the key to that agent's user_id and always send the matching user_id.

Get an API key

Sign up at kovamind.io to get your API key.

License

MIT