MCP API

Quick Start

Configuration Example

{
  "mcpServers": {
    "aperag": {
      "url": "https://rag.apecloud.com/mcp/",
      "headers": {
        "Authorization": "Bearer your-api-key-here"
      }
    }
  }
}

Authentication

• HTTP Authorization Header (Recommended): Authorization: Bearer your-api-key
• Environment Variable (Fallback): APERAG_API_KEY=your-api-key

Get API Key: Login to ApeRAG, create or copy your API Key from settings

Available Tools

1. list_collections

{
  "items": [
    {
      "id": "collection-id",
      "title": "Collection Title",
      "description": "Collection Description"
    }
  ]
}

2. search_collection

{
  "query": "your question",
  "items": [
    {
      "rank": 1,
      "score": 0.95,
      "content": "relevant content",
      "source": "document name",
      "recall_type": "vector_search|graph_search|fulltext_search|summary_search",
      "metadata": {
        "page_idx": 0,
        "document_id": "doc-id",
        "collection_id": "col-id",
        "indexer": "text|vision"
      }
    }
  ]
}

• Empty content: Retrieved via multimodal vector
• Non-empty content: Contains image description

m = item.metadata
asset_url = f"asset://{m['asset_id']}?document_id={m['document_id']}&collection_id={m['collection_id']}&mime_type={m['mimetype']}"

# Default search (recommended) - all methods enabled
results = search_collection(
    collection_id="abc123",
    query="How to deploy applications?"
)

# Vector + Graph only
results = search_collection(
    collection_id="abc123",
    query="deployment strategies",
    use_vector_index=True,
    use_fulltext_index=False,
    use_graph_index=True,
    use_summary_index=False,
    topk=10
)

3. search_chat_files

• ✅ User uploaded files in current conversation
• ✅ Analyzing temporary documents in chat
• ❌ Don't use for persistent knowledge bases (use search_collection)

4. web_search

# Regular search
web_search(query="ApeRAG 2025")

# Site-specific search
web_search(query="deployment docs", source="vercel.com")

# LLM.txt discovery
web_search(search_llms_txt="anthropic.com")

5. web_read

{
  "results": [
    {
      "status": "success",
      "url": "https://example.com",
      "title": "Page Title",
      "content": "Extracted text",
      "word_count": 1234
    }
  ]
}

# Read single page
web_read(url_list=["https://example.com/article"])

# Batch read
web_read(
    url_list=["https://example.com/page1", "https://example.com/page2"],
    max_concurrent=2
)

Practical Examples

Example 1: Knowledge Base Q&A

# 1. List all knowledge bases
collections = list_collections()

# 2. Select a knowledge base
collection_id = collections.items[0].id

# 3. Search (all methods enabled by default)
results = search_collection(
    collection_id=collection_id,
    query="How to optimize performance?"
)

# 4. Process results
for item in results.items:
    print(f"[{item.recall_type}] {item.content}")
    print(f"Source: {item.source}, Score: {item.score}\n")

Example 2: Graph Visualization

# Search with graph retrieval
results = search_collection(
    collection_id="abc123",
    query="relationship between Liu Bei and Zhuge Liang",
    use_graph_index=True
)

# Check for graph data
if results.graph_search and results.graph_search.entities:
    print("Entities:", results.graph_search.entities)
    print("Relationships:", results.graph_search.relationships)
    # Use this data to generate knowledge graph visualization

Example 3: Hybrid Search (KB + Web)

# 1. Search web
web_results = web_search(query="latest AI developments", max_results=3)
urls = [r.url for r in web_results.results]

# 2. Read web content
web_content = web_read(url_list=urls)

# 3. Search internal KB
kb_results = search_collection(
    collection_id="ai-knowledge",
    query="AI development trends"
)

# 4. Synthesize
print("=== Web Results ===")
for r in web_results.results:
    print(f"{r.title}: {r.url}")

print("\n=== Internal Knowledge ===")
for item in kb_results.items:
    print(f"{item.content[:100]}...")

Best Practices

Performance Tips

• Reasonable topk:
  • Too large increases LLM context consumption
  • Too small may miss important information
  • Recommended: 5-10
• Selective Retrieval:
  • Not all queries need full-text search
  • Full-text may return large amounts of text
  • Choose methods based on query type
• Timeout Settings:
  • Graph retrieval may be slow (default 120s)
  • Web search: 30-60s recommended
  • Batch URL read: 60s+ recommended

Common Issues

• Check if collection ID is correct
• Confirm knowledge base indexing is complete
• Try different retrieval method combinations

• Confirm knowledge base has Graph index enabled
• Simple documents may not contain obvious entity relationships

• Check metadata.indexer == "vision"
• Use asset:// protocol for URL
• Ensure all required parameters included (asset_id, document_id, collection_id)

Tool Comparison

Related Links

• MCP Protocol: https://modelcontextprotocol.io/
• ApeRAG GitHub: https://github.com/apecloud/ApeRAG
• API Docs: http://localhost:8000/docs (local deployment)