In-depth architectural comparison of the Knowledge Rag and Artifacta MCP MCP servers. Compare execution transports, security boundaries, tool capabilities, quality scores, and ready-to-paste client installation snippets for Claude, Cursor, Windsurf, and VS Code.
At a Glance & Executive Verdict
Knowledge Rag
Knowledge & Memory · Local stdio
Quality: 63/100 (Good) | Auth: No auth required
Artifacta MCP
Knowledge & Memory · Local stdio
Quality: 57/100 (Good) | Auth: API Key required
Verdict Summary: Choose Knowledge Rag if you need specialized Knowledge & Memory tools running via a local process. Choose Artifacta MCP if your workspace requires Knowledge & Memory integration with local subprocess execution. Both servers can be configured concurrently in your client's mcpServers manifest.
Which MCP Server Should You Choose?
Choose Knowledge Rag when:
You need dedicated capabilities in the Knowledge & Memory domain.
You prefer local stdio subprocess transport architecture.
Your security boundary fits: No auth required (Free / Open Source).
Hybrid search combining semantic search + BM25 keyword search with cross-encoder reranking.
Read-only. No side effects.
Args:
query: Search query text (1–3 keywords recommended; phrase queries also work)
max_results: Maximum number of results (default: 5, max: 20)
category: Optional category filter — one of: security, ctf, logscale, development, general,
redteam, blueteam. Call list_categories() first to see available categories and counts.
hybrid_alpha: Balance between semantic and keyword search. 0.0 = keyword-only (best for exact
technical terms like CVE IDs or tool names), 0.3 = balanced default, 1.0 = semantic-only
(best for conceptual or natural-language queries).
min_score: Minimum normalized relevance score (0.0–1.0) to include a result. Results scoring
below this threshold are discarded. Default 0.0 returns all results. Use 0.2–0.4 to cut
low-relevance noise.
snippet_mode: When true (default), truncates content to ~500 characters at a natural break
point and adds a content_length field with the original size. Use get_document() to
fetch full content when needed. Set to false to return full chunk content.
search_method: Dispatch selector (v4.8.2+). One of ``"auto"`` (router picks FTS5 fast-path
for lexical queries when enabled, hybrid otherwise), ``"hybrid"`` (force hybrid path —
kill switch for suspected router misclassification), or ``"fts5"`` (force FTS5 fast-path
— debug/testing; errors out when the feature is disabled or the index is not ready).
Default ``"auto"`` preserves pre-v4.8.2 behavior byte-for-byte when the fast-path is
disabled in config.
Returns:
JSON string with results including content chunks, source filepath, relevance score, and
search method used. Returns chunks, not full document content.
Usage: Primary search tool — use for any topic or keyword lookup. Prefer search_similar() when
you already have a reference document and want more like it. Prefer get_document() when you
already know the exact filepath and need the full content.
Ready-to-Paste Client Configurations
Paste either (or both) of these JSON server blocks into your client config file (e.g. claude_desktop_config.json or ~/.cursor/mcp.json).
Knowledge Rag is categorized under Knowledge & Memory and uses a local stdio subprocess. In contrast, Artifacta MCP belongs to Knowledge & Memory using local stdio subprocess. Select Knowledge Rag when you need capabilities focused on knowledge & memory and Artifacta MCP when you require tools for knowledge & memory.
Get the full content of a specific document by filepath.
Read-only. No side effects.
Args:
filepath: Relative path to the document within the documents directory
(e.g., "security/technique.md"). Must be an indexed file — use
list_documents() to browse available paths, or search_knowledge()
to find the filepath by topic first.
Returns:
JSON string with full document content and metadata (filepath, category, size).
Usage: Use when you need the complete text of a known file — search_knowledge()
returns chunks, not full docs. Use search_knowledge() first to find the filepath
if unknown. Use list_documents() to browse all available files by category.
reindex_documents
Index or reindex all documents in the knowledge base (runs in background).
``force`` — smart reindex (detect changed files + rebuild BM25). Use after
filesystem edits outside add_document/update_document.
``full_rebuild`` — nuclear rebuild (delete + re-embed). Use only after
embedding-model change or index corruption. Mutually exclusive with resume.
``resume`` — pick up an interrupted smart reindex from
``data/reindex_checkpoint.json``. Falls back to a fresh smart run silently
if the checkpoint is missing/corrupt/drifted (v4.8.0 Fase 4).
Returns a JSON envelope. Poll ``get_reindex_status()`` until
``reindex.active`` becomes false. Add/update/URL tools already auto-index —
use these flags only for the recovery/rebuild scenarios above.
get_reindex_status
Get the current status of a background reindex operation.
Lightweight — does not compute full index statistics. Use this to poll progress
after calling reindex_documents().
Returns:
JSON string with reindex status. When active: operation name, progress (processed/total),
percent complete, indexed/skipped/errors counts, and start time. When inactive: active=false,
plus last_result or last_error from the most recent completed reindex.
Usage: Call repeatedly after reindex_documents() to monitor progress. When reindex.active
becomes false, the operation is complete. Use get_index_stats() for full index health metrics.
list_categories
List all document categories with their document counts.
Read-only. No side effects. Reflects the live index state.
Returns:
JSON string with category names, document counts per category, and total document count.
Usage: Use before filtering search_knowledge() or list_documents() by category to see
which categories exist and how many documents each contains. Use get_index_stats() instead
for broader system health metrics (model name, cache hit rate, BM25 status).
list_documents
List all indexed documents, optionally filtered by category.
Read-only. No side effects.
Args:
category: Optional category filter. Must be a valid category name — call
list_categories() to see available options (e.g., security, ctf, logscale,
development, general, redteam, blueteam).
Returns:
JSON string with list of document filepaths, categories, and metadata for each indexed file.
Usage: Use to browse what's in the index or verify a specific file is indexed. Use
list_categories() first to see valid category names. Use search_knowledge() when you
want to find documents by topic rather than browsing the full list. Use get_document()
to read a specific file once you have its filepath.
get_index_stats
Get statistics and health metrics for the knowledge base index.
Read-only. No side effects.
Returns:
JSON string with system metrics: total documents, total chunks, embedding model name,
BM25 status, query cache hit rate, and file watcher status.
Usage: Use for system health checks — verifying the embedding model loaded, checking
index population, or monitoring cache efficiency. Use list_categories() for per-category
document counts instead. Use evaluate_retrieval() to measure actual search quality with
test queries.
add_document
Add a new document to the knowledge base from raw text content.
Mutating — writes a file to disk and indexes it immediately. No auth required.
Args:
content: Full text content of the document (markdown supported)
filepath: Relative path within documents directory (e.g., "security/new-technique.md").
The subdirectory should match the category.
category: Document category — one of: security, ctf, logscale, development, general,
redteam, blueteam (default: general)
Returns:
JSON string with indexing results (filepath, chunks created, status).
Usage: Use to add new documents from text content. Use add_from_url() instead when
the source is a web page. Use update_document() to replace content of an existing file.
The document is immediately searchable after this call — no manual reindex needed.
update_document
Update the content of an existing document in the knowledge base.
Mutating — overwrites the file on disk and re-indexes immediately. Old chunks are
removed and replaced with new ones. Full content replacement, not a patch.
Args:
filepath: Full or relative path to the document file. Must be an already-indexed
file — use list_documents() to find valid paths.
content: New full-text content to replace the existing content entirely
Returns:
JSON string with update results (old chunk count, new chunk count, status).
Usage: Use to replace a document's content completely. Use add_document() to create
a new file instead. Use remove_document() to delete without replacing. Changes are
immediately searchable — no manual reindex needed.
remove_document
Remove a document from the knowledge base index.
Mutating — removes index entries. If delete_file=True, also permanently deletes
the file from disk (irreversible, cannot be undone).
Args:
filepath: Path to the document file. Must be an indexed document — use
list_documents() to find valid paths.
delete_file: If True, permanently deletes the file from disk in addition to
removing from the index (default: False).
Returns:
JSON string with removal results (filepath, status).
Usage: Use to unindex a document while keeping the file on disk (default). Set
delete_file=True only for permanent removal. Use update_document() to replace
content instead of removing. Use reindex_documents(force=True) if you deleted
the file manually on disk outside of this tool.
add_from_url
Fetch content from a URL, convert to markdown, and add to the knowledge base.
Mutating — makes an outbound HTTP request (requires internet access), strips HTML,
converts to markdown, saves to disk, and indexes immediately.
Args:
url: Full URL to fetch (https:// required). The page must be publicly accessible.
category: Document category — one of: security, ctf, logscale, development, general,
redteam, blueteam (default: general)
title: Optional document title. Auto-detected from the page's <title> tag if omitted.
Returns:
JSON string with indexing results (detected title, filepath, chunks created, status).
Usage: Use to ingest web content (writeups, blog posts, documentation pages) directly
by URL. Use add_document() instead when you already have the text content. The document
is immediately searchable after this call — no manual reindex needed.
search_similar
Find documents semantically similar to a given reference document.
Read-only. No side effects. Uses the document's embedding for similarity comparison.
Args:
filepath: Path to the reference document (must already be indexed — use
list_documents() to verify). E.g., "security/technique.md"
max_results: Number of similar documents to return (default: 5, max: 20)
Returns:
JSON string with list of similar document filepaths and similarity scores (0.0–1.0).
Usage: Use when you have a specific document and want to discover thematically related
ones. Use search_knowledge() instead when you have a text query rather than a reference
document. The reference document must be indexed — call list_documents() to confirm
it exists before calling this tool.
+1 more tools listed on main page
Artifacta MCP Tools (10)
whoami
Return the calling tenant's identity, plan tier, current usage counters (storage bytes, monthly requests, active links), and rate limits. Use this once at the start of an agent run to confirm authentication and to size subsequent operations against quota. Free of side effects and quota-cheap.
list_artifacts
List artifacts owned by the calling tenant, newest first. Supports filters by `session_id`, `agent_id`, `filename` (exact match), `content_type`, `created_after` / `created_before` (ISO 8601), and one or more `metadata.<key>=<value>` pairs (multi-key requires Pro). Returns a page of artifact records and a `next_cursor` to fetch the next page. Use this to discover what an agent or pipeline produced when you only know a session or agent ID.
get_artifact
Fetch metadata for a single artifact by ID: filename, content type, size, content hash, session/agent IDs, custom metadata, expiry, creation timestamp. Does NOT return the file bytes — call `get_artifact_download_url` for that. Returns `artifact_not_found` for unknown IDs, `artifact_already_deleted` (HTTP 410) for soft-deleted ones, `artifact_expired` (410) for those past their TTL.
get_artifact_download_url
Generate a short-lived presigned URL (1 hour) the agent can use to download the artifact's bytes directly from Cloudflare R2. Use this when the agent itself needs to consume the file. For sharing with humans, use `create_download_link` instead — that produces a stable `dl.artifacta.io/lnk_…` URL with configurable expiry.
list_sessions
List session IDs synthesized from the calling tenant's artifacts, ordered by most recent activity. Each entry includes artifact count, seal status, and first/last activity timestamps. Sessions are not first-class — they exist only as long as artifacts reference them.
store_artifact
Upload a file as a new artifact in a single call. Provide EITHER up to ~10 MB of base64-encoded bytes via `content`, OR a local filesystem `path` that the MCP server reads and streams as multipart/form-data (up to 500 MB). For files larger than 500 MB, use `request_upload_url` (Pro only) instead — `store_artifact` returns `file_too_large` for them. Tags the artifact with `session_id` / `agent_id` / `metadata` for later retrieval and returns the full artifact record including its new `artifact_id` and `content_hash`.
Path uploads are confined. The `path` argument is constrained to the launcher-configured allow-list (default: the MCP server's CWD). Paths outside the allow-list, paths traversing symlinks out of it, and paths to known-sensitive locations (`~/.ssh`, `~/.aws`, `/etc/`, etc.) are refused with `invalid_request`.
For crash-safe retries, supply your own `idempotency_key` (any string ≤256 chars): a replay within 24h returns the original artifact and never double-bills. If you omit it, the server auto-generates one and returns it under `_meta.idempotency_key`, but that key protects only in-process retries within a single call — it is lost if the server restarts, so pre-commit your own key when durability matters.
request_upload_url
Reserve a presigned R2 PUT URL for a file too large to send through `store_artifact` (over 500 MB up to 5 GB). Returns an `upload_url`, headers to include in the PUT, and an `artifact_id` in `pending` state. The agent (or its environment) PUTs the bytes directly to R2, then calls `complete_upload`. Pro plan only. Most agents should use `store_artifact` and let the MCP server pick the path automatically.
Not retry-safe: this endpoint does not support idempotency keys, so on an HTTP 5xx or network error the reservation may or may not have been created. Do NOT blindly retry — the error guidance tells you to first call `list_artifacts` with the same `session_id`/`agent_id` to detect any pending artifact, so you don't create a duplicate.
complete_upload
Finalize an artifact previously reserved via `request_upload_url` after the bytes have been PUT to the presigned URL. Server verifies the blob, computes the content hash, transitions the artifact from `pending` to `active`, and increments tenant usage. Calling this on an already-active artifact is idempotent and returns the existing record. Calling before the PUT completes returns `upload_not_found` — wait and retry.
publish_artifact
Publish an existing artifact as a polished, shareable public page at https://artifacta.io/a/{slug}. Composes with store_artifact (store first, then publish). Returns a public_url anyone can open without an Artifacta account. Default visibility is unlisted (link-only); pass visibility:"public" for gallery-eligible later. Idempotent: re-publishing the same artifact_id updates the existing page and keeps the same URL.
unpublish_artifact
Remove the public page for an artifact, making the public URL inaccessible. The artifact itself is not deleted — only its shareable page is taken down. The URL stops resolving immediately. Idempotent: calling unpublish on an already-unpublished artifact is a no-op.
Local RAG system for Claude Code with hybrid search (BM25 + semantic), cross-encoder reranking, markdown-aware chunking, query expansion, and 28 MCP tools. Runs entirely offline with zero external servers.
The artifact store for AI agents. Every output your agents produce — persisted, retrievable, shareable. Across runs, sessions, and tools. Session/agent metadata, content-hash dedup, expiring share links; 11 tools with path-confined uploads and destructive actions gated by default. TypeScript (npx @artifacta-mcp/mcp) and Python (pipx run artifacta-mcp).