Vectara MCP Server

Vectara MCP Server

🔌 兼容 Claude Desktop 及其他任何 MCP 客户端！

Vectara MCP 也兼容任何 MCP 客户端

Model Context Protocol（MCP）是一项开放标准，可让 AI 系统与各种数据源和工具无缝交互，从而建立安全的双向连接。

Vectara-MCP 通过 MCP 协议，为任何智能体应用提供快速、可靠且减少幻觉的 RAG 能力，由 Vectara 的 Trusted RAG 平台提供支持。

安装

你可以直接从 PyPI 安装此软件包：

pip install vectara-mcp

快速开始

默认安全（带身份验证的 HTTP/SSE）

# Start server with secure HTTP transport (DEFAULT)
python -m vectara_mcp
# Server running at http://127.0.0.1:8000 with authentication enabled

本地开发模式（STDIO）

# For Claude Desktop or local development (less secure)
python -m vectara_mcp --stdio
# ⚠️ Warning: STDIO transport is less secure. Use only for local development.

配置选项

# Custom host and port
python -m vectara_mcp --host 0.0.0.0 --port 8080

# SSE transport mode
python -m vectara_mcp --transport sse --path /sse

# Disable authentication (DANGEROUS - dev only)
python -m vectara_mcp --no-auth

传输模式

HTTP 传输（默认 - 推荐）

• 安全性： 通过 bearer token 内置身份验证
• 加密： 支持 HTTPS
• 速率限制： 默认每分钟 100 个请求
• CORS 保护： 可配置的来源验证
• 使用场景： 生产部署、云环境

SSE 传输

• 流式传输： 使用 Server-Sent Events 实时更新
• 身份验证： 支持 bearer token
• 兼容性： 可与旧版 MCP 客户端配合使用
• 使用场景： 实时流式应用

STDIO 传输

• ⚠️ 安全警告： 无传输层安全性
• 性能： 本地通信延迟低
• 使用场景： 本地开发、Claude Desktop
• 要求： 必须通过 --stdio 标志显式启用

环境变量

# Required
export VECTARA_API_KEY="your-api-key"

# Optional
export VECTARA_AUTHORIZED_TOKENS="token1,token2"  # Additional auth tokens
export VECTARA_ALLOWED_ORIGINS="http://localhost:*,https://app.example.com"
export VECTARA_TRANSPORT="http"  # Default transport mode
export VECTARA_AUTH_REQUIRED="true"  # Enforce authentication

身份验证

HTTP/SSE 传输

使用 HTTP 或 SSE 传输时，默认需要身份验证：

# Using curl with bearer token
curl -H "Authorization: Bearer $VECTARA_API_KEY" \
     -H "Content-Type: application/json" \
     -X POST http://localhost:8000/call/ask_vectara \
     -d '{"query": "What is Vectara?", "corpus_keys": ["my-corpus"]}'

# Using X-API-Key header (alternative)
curl -H "X-API-Key: $VECTARA_API_KEY" \
     http://localhost:8000/sse

禁用身份验证（仅限开发环境）

# ⚠️ NEVER use in production
python -m vectara_mcp --no-auth

可用工具

API 密钥管理

• setup_vectara_api_key： 为当前会话配置并验证 Vectara API 密钥（仅需设置一次）。

  参数：

  • api_key：str，你的 Vectara API 密钥（必填）。

  返回：

  • 包含已屏蔽 API 密钥的成功确认信息，或验证错误。

• clear_vectara_api_key： 从服务内存中清除已存储的 API 密钥。

  返回：

  • 确认消息。

查询工具

• ask_vectara: 使用 Vectara 运行 RAG 查询，返回搜索结果和生成的回答。

  参数：

  • query: str，要运行的用户查询 — 必填。
  • corpus_keys: list[str]，用于搜索的 Vectara 语料库密钥列表 — 必填。
  • n_sentences_before: int，在上下文中包含答案之前的句子数 — 可选，默认值为 2。
  • n_sentences_after: int，在上下文中包含答案之后的句子数 — 可选，默认值为 2。
  • lexical_interpolation: float，词法插值量 — 可选，默认值为 0.005。
  • max_used_search_results: int，使用的搜索结果最大数量 — 可选，默认值为 10。
  • generation_preset_name: str，要使用的生成预设名称 — 可选，默认值为 "vectara-summary-table-md-query-ext-jan-2025-gpt-4o"。
  • response_language: str，回答所用的语言 — 可选，默认值为 "eng"。

  返回：

  • Vectara 的响应，包括生成的回答和搜索结果。

• search_vectara: 使用 Vectara 运行语义搜索查询，不进行生成。

  参数：

  • query: str，要运行的用户查询 — 必填。
  • corpus_keys: list[str]，用于搜索的 Vectara 语料库密钥列表 — 必填。
  • n_sentences_before: int，在上下文中包含答案之前的句子数 — 可选，默认值为 2。
  • n_sentences_after: int，在上下文中包含答案之后的句子数 — 可选，默认值为 2。
  • lexical_interpolation: float，词法插值量 — 可选，默认值为 0.005。

  返回：

  • Vectara 的响应，包括匹配的搜索结果。

分析工具

• correct_hallucinations: 使用 Vectara 的 VHC（Vectara 幻觉纠正）API，识别并纠正生成文本中的幻觉。

  参数：

  • generated_text: str，要分析幻觉的生成文本 — 必填。
  • documents: list[str]，用于比对的源文档列表 — 必填。
  • query: str，导致生成该文本的原始用户查询 — 可选。

  返回：

  • JSON 格式的字符串，包含纠正后的文本和详细的纠正信息。

• eval_factual_consistency: 使用 Vectara 专用的事实一致性评估 API，评估生成文本与源文档之间的事实一致性。

  参数：

  • generated_text: str，要评估事实一致性的生成文本 — 必填。
  • documents: list[str]，用于比对的源文档列表 — 必填。
  • query: str，导致生成该文本的原始用户查询 — 可选。

  返回：

  • JSON 格式的字符串，包含事实一致性评估结果和评分。

注意： 必须先使用 setup_vectara_api_key 工具配置 API 密钥，或设置 VECTARA_API_KEY 环境变量。

使用 Claude Desktop 进行配置

若要与 Claude Desktop 配合使用，请更新配置以使用 STDIO 传输：

{
  "mcpServers": {
    "Vectara": {
      "command": "python",
      "args": ["-m", "vectara_mcp", "--stdio"],
      "env": {
        "VECTARA_API_KEY": "your-api-key"
      }
    }
  }
}

或者使用 uv：

{
  "mcpServers": {
    "Vectara": {
      "command": "uv",
      "args": ["tool", "run", "vectara-mcp", "--stdio"]
    }
  }
}

注意： Claude Desktop 需要使用 STDIO 传输。虽然其安全性低于 HTTP，但用于本地桌面应用是可以接受的。

在 Claude Desktop App 中使用

安装完成并配置好 Claude 桌面应用后，必须完全关闭并重新打开 Claude 桌面应用，才能看到 Vectara-mcp 服务。应用左下角应会出现一个锤子图标，表示有可用的 MCP 工具；点击该图标可查看 Vectara-search 和 Vectara-extract 工具的更多详情。

现在，Claude 将能够完整访问 Vectara-mcp 服务，包括全部六个 Vectara 工具。

安全设置工作流

首次设置（每个会话仅需一次）：

1. 安全地配置 API 密钥：

setup-vectara-api-key
API key: [your-vectara-api-key]

设置完成后，可使用任意工具，无需暴露 API 密钥：

Vectara 工具示例

1. 带生成的 RAG 查询：

ask-vectara
Query: Who is Amr Awadallah?
Corpus keys: ["your-corpus-key"]

2. 仅语义搜索：

search-vectara
Query: events in NYC?
Corpus keys: ["your-corpus-key"]

3. 幻觉检测与纠正：

correct-hallucinations
Generated text: [text to check]
Documents: ["source1", "source2"]

4. 事实一致性评估：

eval-factual-consistency
Generated text: [text to evaluate]
Documents: ["reference1", "reference2"]

安全最佳实践

1. 生产环境始终使用 HTTP 传输 - 切勿将 STDIO 传输暴露到网络
2. 保持启用身份验证 - 仅在本地测试时使用 --no-auth 禁用
3. 生产环境使用 HTTPS - 部署在采用 TLS 终止的反向代理后
4. 正确配置 CORS - 设置 VECTARA_ALLOWED_ORIGINS 以限制访问
5. 定期轮换 API 密钥 - 更新 VECTARA_API_KEY 和 VECTARA_AUTHORIZED_TOKENS
6. 监控速率限制 - 默认值为每分钟 100 次请求，请根据需求调整

详细的安全指南请参阅 SECURITY.md。

支持

如有问题、疑问或希望参与贡献，请访问： https://github.com/vectara/vectara-mcp