How It Works

Vectorless provides a remote MCP server at https://api.vectorless.store/mcp. Your AI assistant connects to it directly over the internet — no local process, no API keys to manage.

Authentication uses OAuth 2.1 with PKCE: on first connect your AI client opens the Vectorless dashboard where you log in and approve access. After that, it just works.

┌──────────────────────────────────────────────────────────────┐
│        Claude Desktop / Cursor / Windsurf / Claude Code      │
│                                                              │
│   1. Add the remote MCP URL                                  │
│   2. OAuth redirect → Vectorless Dashboard (login + consent) │
│   3. Token issued → MCP session active                       │
│   4. AI calls tools via Streamable HTTP + SSE                │
└───────────────────────────┬──────────────────────────────────┘
                            │
                            │  Streamable HTTP + SSE
                            ▼
┌──────────────────────────────────────────────────────────────┐
│                  api.vectorless.store/mcp                     │
│                                                              │
│   OAuth 2.1 (PKCE)          7 Tools                          │
│   ┌──────────────────┐      ┌──────────────────────────┐    │
│   │ /.well-known/    │      │ vectorless_list_documents │    │
│   │   oauth-*        │      │ vectorless_ingest_document│    │
│   │ /oauth/authorize │      │ vectorless_get_document   │    │
│   │ /oauth/token     │      │ vectorless_get_tree       │    │
│   │ /oauth/register  │      │ vectorless_get_section    │    │
│   └──────────────────┘      │ vectorless_query          │    │
│                              │ vectorless_delete_document│    │
│   Scopes:                    └──────────────────────────┘    │
│   • documents:read                                           │
│   • documents:write          Vectorless Engine               │
│   • query                    (retrieval + ingestion)         │
└──────────────────────────────────────────────────────────────┘

Setup (Remote — Recommended)

Add the remote URL to your AI client config. No installation needed.

Claude Desktop

Settings → Developer → Edit Config:

{
  "mcpServers": {
    "vectorless": {
      "url": "https://api.vectorless.store/mcp"
    }
  }
}

Cursor

.cursor/mcp.json:

{
  "mcpServers": {
    "vectorless": {
      "url": "https://api.vectorless.store/mcp"
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "vectorless": {
      "url": "https://api.vectorless.store/mcp"
    }
  }
}

Claude Code

.claude/settings.json:

{
  "mcpServers": {
    "vectorless": {
      "url": "https://api.vectorless.store/mcp"
    }
  }
}

That's it. On first use, your AI client opens the Vectorless dashboard in your browser. Log in (Google, GitHub, or email), approve the permissions, and you're connected.

OAuth Scopes

When you authorize, the consent screen shows these permissions:

| Scope | Grants access to | |-------|-----------------| | documents:read | List documents, get metadata, browse tree, fetch sections | | documents:write | Upload new documents, delete existing ones | | query | Run natural language queries against documents |

You choose which scopes to grant. The AI agent can only use tools matching your approved scopes.

Available Tools

vectorless_list_documents

List all your documents with status, metadata, and pagination.

vectorless_ingest_document

Upload a document from a URL or base64 content. Supports PDF, DOCX, Markdown, HTML, plain text. Documents are parsed into hierarchical section trees with AI-generated summaries.

vectorless_get_document

Get metadata and processing status for a document (pending → parsing → summarizing → ready).

vectorless_get_tree

View the hierarchical outline — sections with titles, summaries, depth, and token counts. Use this to understand what's in a document before querying.

vectorless_get_section

Fetch the full content of a specific section by ID.

vectorless_query

Ask a natural language question. An LLM navigates the document tree to find and return the most relevant sections with full content, strategy, timing, and cost.

vectorless_delete_document

Permanently delete a document and all its sections.

Example Conversation

You:    Upload this paper: https://arxiv.org/pdf/2301.00001
Claude: [calls vectorless_ingest_document]
        Done — doc_abc123 is ready (14 sections, 48,200 tokens).

You:    What's the structure?
Claude: [calls vectorless_get_tree]
        Introduction (1,200 tokens)
          Background (800 tokens)
          Related Work (2,400 tokens)
        Methodology (3,600 tokens)
          Data Collection (1,100 tokens)
          Model Architecture (2,500 tokens)
        Results (4,200 tokens)
        Conclusion (900 tokens)

You:    What model architecture did they use?
Claude: [calls vectorless_query]
        Found 2 relevant sections (chunked-tree, 340ms):

        ## Model Architecture
        We employ a transformer-based encoder with 12 attention heads...

        ## Results
        The model achieved 94.2% accuracy on the benchmark...

Fallback: Local Stdio Server

If your MCP client doesn't support remote servers, run the stdio bridge locally:

npx vectorless-mcp

{
  "mcpServers": {
    "vectorless": {
      "command": "npx",
      "args": ["-y", "vectorless-mcp"],
      "env": {
        "VECTORLESS_API_KEY": "vl_..."
      }
    }
  }
}

| Variable | Default | Description | |----------|---------|-------------| | VECTORLESS_API_KEY | — | API key (required for remote, optional for self-hosted) | | VECTORLESS_BASE_URL | https://api.vectorless.store | Server URL | | VECTORLESS_TRANSPORT | http | Wire protocol (http or connect) |

Self-Hosted

Point the MCP to your own Vectorless instance:

{
  "mcpServers": {
    "vectorless": {
      "url": "https://your-server.com/mcp"
    }
  }
}

Or via stdio:

{
  "mcpServers": {
    "vectorless": {
      "command": "npx",
      "args": ["-y", "vectorless-mcp"],
      "env": {
        "VECTORLESS_BASE_URL": "https://your-server.com",
        "VECTORLESS_API_KEY": "your-key"
      }
    }
  }
}

License

MIT