Skip to content
MachiOnCoffee
Vectora
Getting Started
Quickstart MCP

Quickstart MCP

PT | EN

This guide allows you to integrate Vectora with Claude Desktop via MCP in less than 5 minutes.

Prerequisites: Vectora installed globally (vectora --version) and Claude Desktop installed (download).

Step 1: Locate the Configuration File

macOS / Linux 

# Claude Desktop configuration file
open ~/.claude/claude_desktop_config.json

# If it does not exist, create it with:
mkdir -p ~/.claude
touch ~/.claude/claude_desktop_config.json

Windows 

# Configuration file (WSL2 or Windows)
"$env:APPDATA\Claude\claude_desktop_config.json"

# If it does not exist, create it with:
New-Item -Path "$env:APPDATA\Claude" -ItemType Directory -Force

Step 2: Add Vectora as an MCP Server

Edit claude_desktop_config.json:

{
  "mcpServers": {
    "vectora": {
      "command": "vectora",
      "args": ["mcp-serve"],
      "env": {
        "GEMINI_API_KEY": "sk-xxx...",
        "VOYAGE_API_KEY": "pa-xxx...",
        "VECTORA_NAMESPACE": "my-project"
      }
    }
  }
}

Alternative: Use System Environment Variables

If you already have GEMINI_API_KEY and VOYAGE_API_KEY defined:

{
  "mcpServers": {
    "vectora": {
      "command": "vectora",
      "args": ["mcp-serve"]
    }
  }
}

Step 3: Restart Claude Desktop 

# Completely close Claude Desktop and open it again
# This loads the new MCP configuration

Step 4: Test the Connection

Via Claude Desktop Chat

Open Claude Desktop and test:

Show me the available files using Vectora

Claude should respond with something like:

I have access to Vectora, a code context engine. Let me check what files are available in your project.

[Vectora is now searching your codebase...]

Available files in namespace 'my-project':
- src/auth/jwt.ts (authentication)
- src/services/database.ts (database layer)
- docs/README.md (documentation)
...

Verify MCP Status

If you receive an error:

  1. Open MCP Inspector (in Claude Desktop: Menu → Settings → Developer Tools).
  2. Search for “vectora” in the server list.
  3. Status should be “Connected”.

If it is not connected:

  • Verify that vectora --version works in the terminal.
  • Check the claude_desktop_config.json file (JSON syntax).
  • Restart Claude Desktop.

Step 5: Your First Vectora Command

Explore the Codebase 

What is the structure of this project? List the main directories.

Claude uses file_list via Vectora.

Search Context 

How does JWT authentication work in this project? Find the implementation.

Claude uses context_search for semantic search.

Analyze a File 

Read and explain the src/main.ts file

Claude uses file_read to read the file.

Project Structure

After running vectora init, you will have:

my-project/
├── vectora.config.yaml # Project configuration
├── AGENTS.md # Agent memory (auto-generated)
├── .vectora/ # Cache and local indices
│ ├── embeddings/ # Embedding cache
│ └── index.json # Index metadata
├── src/ # Your code
└── .env # Environment variables (never commit!)

Available MCP Commands

CommandWhat it doesExample
context_searchSemantic search in codebase“JWT authentication”
file_readReads a filesrc/main.ts
file_listLists files recursivelysrc/
file_writeWrites or modifies a fileCreating a new file
file_editEdits part of a fileChanging a function
grep_searchSearch via regexSpecific patterns

Troubleshooting

Error: Vectora MCP server not found

Cause: vectora is not in your PATH.

Solution:

# Check where vectora is installed
which vectora # macOS/Linux
where.exe vectora # Windows

# If not found, reinstall:
npm install -g @kaffyn/vectora

Error: Connection refused

Cause: Vectora cannot connect to the Gemini/Voyage API.

Solution:

# Verify API keys
echo $GEMINI_API_KEY
echo $VOYAGE_API_KEY

# If empty, configure:
export GEMINI_API_KEY="sk-xxx"
export VOYAGE_API_KEY="pa-xxx"

Error: Project not found

Cause: Namespace does not exist.

Solution:

# Initialize the project
vectora init --name "My Project"

# Or specify in claude_desktop_config.json:
"VECTORA_NAMESPACE": "my-project"

Claude does not use Vectora automatically

Cause: Claude doesn’t detect that the tool is relevant.

Solution: Be explicit:

Use Vectora to search for information about authentication in this project.

Next Steps

FAQ

Q: Can I use Vectora with other agents besides Claude? A: Yes! See Gemini Integration and Custom Agents.

Q: Does Vectora work offline? A: Partially. Context search requires internet (Voyage API). File operations work offline.

Q: How to debug MCP connections? A: Use the MCP Inspector in Claude Desktop (Menu → Developer Tools → MCP Inspector).

Next: Learn about Troubleshooting.

Part of the Vectora ecosystem · Open Source (MIT) · Contributors

TroubleshootingConfiguration