@mooosamir/vkp-mcp

MCP server for Vector Knowledge Platform (VKB/VKP) — semantic search over knowledge bases, returning AI-ready text chunks.

Prerequisites

1. A running Vector Knowledge Platform instance (local or hosted).
2. An API key with search scope from the Customer Dashboard → API Keys.

Install in Cursor

Add to your Cursor MCP settings (~/.cursor/mcp.json or project .cursor/mcp.json):

Search all accessible projects:

{
  "mcpServers": {
    "vkb": {
      "command": "npx",
      "args": ["-y", "@mooosamir/vkp-mcp"],
      "env": {
        "VKP_BASE_URL": "http://localhost:8000",
        "VKP_API_KEY": "vkp_live_YOUR_KEY",
        "VKP_PROJECTS": "all"
      }
    }
  }
}

Search specific projects (comma-separated list):

{
  "mcpServers": {
    "vkb": {
      "command": "npx",
      "args": ["-y", "@mooosamir/vkp-mcp"],
      "env": {
        "VKP_BASE_URL": "http://localhost:8000",
        "VKP_API_KEY": "vkp_live_YOUR_KEY",
        "VKP_PROJECTS": "proj_default,proj_hr"
      }
    }
  }
}

Environment variables

| Variable | Required | Description | |----------|----------|-------------| | VKP_BASE_URL | yes | Platform base URL (e.g. http://localhost:8000) | | VKP_API_KEY | yes | API key with search scope (vkp_live_...) | | VKP_PROJECTS | yes | "all" or comma-separated project ids (e.g. proj_default,proj_hr) |

Tool: get_knowledge

Retrieves answers and factual information from the knowledge base. The AI should use this tool whenever a question may depend on uploaded documents or internal knowledge.

Parameters

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | query | string | yes | Search query | | top_k | number (1–100) | no | Max chunks (default: 5) | | filters | object | no | Metadata filters |

Example

{
  "query": "What is the vacation policy?",
  "top_k": 5
}

Response

Returns two text blocks:

1. Markdown — ready to inject into an AI prompt.
2. JSON — structured chunks with rank, chunk_id, document_id, score, text, and metadata.

Local development

cd vkp_mcp
npm install
npm run build
VKP_BASE_URL=http://localhost:8000 VKP_API_KEY=vkp_live_... VKP_PROJECTS=all npm start

Publishing to npm

Scoped package @mooosamir/vkp-mcp publishes under the @mooosamir npm scope.

npm login
# Create org at https://www.npmjs.com/org/create
cd vkp_mcp
npm publish --access public

Troubleshooting

| Error | Fix | |-------|-----| | 401 invalid_api_key | Check VKP_API_KEY is correct and active | | 403 project_access_denied | API key is not scoped to the configured project(s) | | 403 insufficient_permission | API key needs search scope | | 429 rate_limit_exceeded | Wait and retry | | 404 on npm publish to @vkb/mcp | Publish under @mooosamir/vkp-mcp or add your user to the @vkb npm org | | no_accessible_projects | Create a project or set VKP_PROJECTS=all with a key scoped to all projects |

License

MIT