Apcone is a tenant-scoped RAG storage service for internal knowledge. It gives your backend or agent stack one place to ingest documents, chunk and embed text, store vectors in Qdrant, search with semantic plus lexical fallback, and expose the same knowledge through HTTP APIs, a Python SDK, CLI commands, and MCP tools.
Use it when you need a small, understandable retrieval layer before building a
full agent platform: upload text or PDFs, index them by tenant_id and scope,
then search them from an app, script, worker, or MCP-compatible agent.
| Area | What you get |
|---|---|
| HTTP API | Document ingest, upload, search, chunk read, reindex, delete, job polling, health checks. |
| Background ingestion | Redis/RQ worker pipeline for text and PDF uploads, including OCR routing for scanned PDFs. |
| Vector storage | Qdrant collection management, embeddings with FastEmbed, PostgreSQL metadata and lexical fallback. |
| MCP server | Streamable HTTP MCP endpoint at /mcp/ with authenticated knowledge tools for agents. |
| Python SDK | Async ApconeAsyncClient and ApconeMCPClient wrappers for app and agent code. |
| CLI | Local admin commands for API keys, health, documents, search, and jobs. |
uv sync
cp .env.example .env
docker compose up -d postgres redis qdrant
uv run alembic upgrade head
uv run uvicorn app.main:app --reloadCreate an API key:
uv run python -m app.cli api-key create --name local-admin --tenant-id default --role admin
export APCONE_API_KEY=<api_key_from_create_output>Ingest and search a note:
curl -X POST http://127.0.0.1:8000/documents/ingest \
-H "Authorization: Bearer $APCONE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Refund Policy",
"content": "Refunds are available within 14 days.",
"source": "policy.md"
}'
curl -X POST http://127.0.0.1:8000/documents/search \
-H "Authorization: Bearer $APCONE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "refund window", "top_k": 3}'The API key may be sent as Authorization: Bearer <key> or X-API-Key: <key>.
Health endpoints stay public for liveness checks.
import asyncio
from apcone_sdk import ApconeAsyncClient, ApconeMCPClient
async def main() -> None:
api_key = "<apcone_api_key>"
async with ApconeAsyncClient("http://127.0.0.1:8000", api_key) as client:
created = await client.ingest_document(
title="SDK note",
content="Apcone can search tenant-scoped documents.",
source="sdk-example",
)
results = await client.search_documents("tenant-scoped search")
print(created.document.id, results[0].content)
mcp_client = ApconeMCPClient.from_base_url("http://127.0.0.1:8000", api_key)
mcp_results = await mcp_client.search_documents("tenant-scoped search")
print(mcp_results.result_count)
asyncio.run(main())Start with docs/getting-started.md if this is your first run. Use docs/http-api.md for endpoint contracts, docs/sdk.md for Python integration, and docs/mcp.md for agent tooling.
| Guide | Purpose |
|---|---|
| Documentation index | Choose the right reading path. |
| Getting started | Run Apcone locally and perform the first search. |
| Configuration | Understand every important environment variable. |
| HTTP API | Use every endpoint with request and response examples. |
| Python SDK | Integrate Apcone from async Python code. |
| MCP tools | Connect MCP clients and call agent-facing tools. |
| PDF ingestion | Upload PDFs, run workers, and understand OCR routing. |
| CLI | Manage keys, inspect documents, search, and view jobs. |
| Operations | Health checks, troubleshooting, and performance notes. |
| Architecture | How FastAPI, PostgreSQL, Redis, Qdrant, workers, SDK, and MCP fit together. |
With .env.example copied to .env, local ports are:
| Service | URL |
|---|---|
| Apcone API | http://127.0.0.1:8000 |
| MCP endpoint | http://127.0.0.1:8000/mcp/ |
| PostgreSQL | 127.0.0.1:5433 |
| Redis | 127.0.0.1:6380 |
| Qdrant API/UI | http://127.0.0.1:6333 |
| Qdrant dashboard | http://127.0.0.1:6333/dashboard |
| PDF scanner gRPC | 127.0.0.1:50051 |
Run the full test suite with:
uv run pytestApcone is intentionally small: clear FastAPI routes, focused services, explicit Pydantic schemas, SQLAlchemy models, and tests around the core API, MCP, SDK, storage, queue, scanner, and CLI behavior.