cob-rag-mcp is an MCP server and a full CLI for cob-rag-engine, the self-hosted knowledge layer for AI assistants and agents. Plug a business's own knowledge base into Claude, Cursor, VS Code, n8n or any MCP client, or work with it straight from the shell. One set of 52 tools, two ways in.
# run the MCP server, nothing to install npx -y cob-rag-mcp start # or install both commands, then sign in npm i -g cob-rag-mcp cob-rag-engine login --url http://127.0.0.1:8000 --key ck_...
# a first search: passages with sources, no model needed cob-rag-engine search "How long should I fast before a cholesterol test?" --final-k 3 [1] Fasting before a lipid profile [faq-fasting-lipid] (score 0.066) For a lipid profile (cholesterol test) fast for 10 to 12 hours before your sample is taken. ...
An agent is only as useful as what it knows about the business it works for: the returns policy, the price list, which tests need fasting. cob-rag-engine holds that knowledge, one isolated knowledge base (a corpus) per business. This package puts it where agents and people work.
Claude, Cursor, VS Code, n8n, any client that speaks MCP.
search to pull the right passages, with sources, and answers from them with its own model.ask for a complete cited answer written by the model configured in your engine.COB_RAG_ALLOW_DESTRUCTIVE=true.You, scripts, CI, an agent's own terminal.
search "...", ingest records, corpora create, usage: every tool is also a command.--json for scripts.--yes.CLI (cob-rag-engine) | MCP server (cob-rag-mcp start) | |
|---|---|---|
| Who it is for | You, scripts, CI, an agent's own terminal | Claude, Cursor, VS Code, n8n, any MCP client |
| Output | Tables; --json for machines | JSON tool results |
| Destructive actions | Asks first, or --yes | Hidden unless COB_RAG_ALLOW_DESTRUCTIVE=true |
| Transports | n/a | stdio (default) and streamable HTTP |
cob-rag-mcp is only a client. It talks to a cob-rag-engine that you run yourself, on your laptop, your server or your cloud, using the URL and key you give it. Nothing is sent anywhere else.
One docker compose up. Start with the engine's quick start, then come back. New to it? The engine's site has the overview.
The admin key (RAG_ADMIN_API_KEY in the engine's .env), a tenant key (tk_...) or a corpus key (ck_...). Which one?
npx -y cob-rag-mcp start with nothing installed, or npm i -g cob-rag-mcp for both commands. Needs Node.js 22 or newer.
Set COB_RAG_URL and COB_RAG_API_KEY, or save them once with cob-rag-engine login.
For ask, a model must be configured in the engine (engine default, per corpus, or per request with your own key). search needs no model at all.
| Setting | Environment variable | Flag | Default |
|---|---|---|---|
| Engine URL | COB_RAG_URL | --url | http://127.0.0.1:8000 |
Engine key (admin, tk_ or ck_) | COB_RAG_API_KEY | --key | none |
| Default corpus for tenant and admin keys | COB_RAG_CORPUS_ID | --corpus-id per command | none |
| Offer destructive tools over MCP | COB_RAG_ALLOW_DESTRUCTIVE | --allow-destructive | false |
| Hide or refuse every write | COB_RAG_READ_ONLY | --read-only | false |
The only directory MCP upload_file may read | COB_RAG_UPLOAD_DIR | none (upload off) | |
| HTTP mode: let keyless requests use the server key | COB_RAG_HTTP_USE_SERVER_KEY | false | |
| Config file location | COB_RAG_CONFIG | --config | see the README |
Priority: command-line flags, then environment variables, then your config file, then defaults. Bring your own model key with COB_RAG_LLM_PROVIDER, COB_RAG_LLM_MODEL, COB_RAG_LLM_API_KEY and COB_RAG_LLM_BASE_URL; they are sent as X-LLM-* headers on search and ask only. The README has the full list.
Swap in a tenant or admin key to manage corpora; the tool list follows the key. Already ran cob-rag-engine login? Then the env block is optional: the server reads the saved config.
claude mcp add cob-rag \
-e COB_RAG_URL=http://127.0.0.1:8000 \
-e COB_RAG_API_KEY=ck_your_corpus_key \
-- npx -y cob-rag-mcp start
Already logged in? claude mcp add cob-rag -- npx -y cob-rag-mcp start is enough.
{
"mcpServers": {
"cob-rag": {
"command": "npx",
"args": ["-y", "cob-rag-mcp", "start"],
"env": {
"COB_RAG_URL": "http://127.0.0.1:8000",
"COB_RAG_API_KEY": "ck_your_corpus_key"
}
}
}
}
macOS: ~/Library/Application Support/Claude/. Windows: %APPDATA%\Claude\. Restart Claude Desktop afterwards.
{
"mcpServers": {
"cob-rag": {
"command": "cmd",
"args": ["/c", "npx", "-y", "cob-rag-mcp", "start"],
"env": {
"COB_RAG_URL": "http://127.0.0.1:8000",
"COB_RAG_API_KEY": "ck_your_corpus_key"
}
}
}
}
The cmd /c variant. Or install globally and use cob-rag-mcp as the command. Use 127.0.0.1, not localhost: on Windows it can resolve to IPv6 ::1, which Docker Desktop may not forward.
{
"mcpServers": {
"cob-rag": {
"command": "npx",
"args": ["-y", "cob-rag-mcp", "start"],
"env": {
"COB_RAG_URL": "http://127.0.0.1:8000",
"COB_RAG_API_KEY": "ck_your_corpus_key"
}
}
}
}
The first path covers all projects, the second one project.
{
"inputs": [
{ "type": "promptString", "id": "cob-rag-key", "description": "cob-rag-engine key", "password": true }
],
"servers": {
"cob-rag": {
"type": "stdio",
"command": "npx",
"args": ["-y", "cob-rag-mcp", "start"],
"env": {
"COB_RAG_URL": "http://127.0.0.1:8000",
"COB_RAG_API_KEY": "${input:cob-rag-key}"
}
}
}
}
The inputs block makes VS Code ask for the key once and store it securely, so it never sits in the file.
cob-rag-mcp start --transport http --host 127.0.0.1 --port 3333 # MCP over HTTP at http://127.0.0.1:3333/mcp # Claude Code over HTTP claude mcp add --transport http cob-rag http://127.0.0.1:3333/mcp \ --header "Authorization: Bearer ck_..."
n8n: add an MCP Client Tool node, endpoint http://127.0.0.1:3333/mcp, transport HTTP Streamable, authentication Bearer, token = the corpus key. Health check: GET /health answers {"status":"ok"} without a key.
Carries the caller's own engine key, as Authorization: Bearer <key> or X-API-Key: <key>. A request without a key gets 401, unless you set COB_RAG_HTTP_USE_SERVER_KEY=true on purpose.
One fresh MCP server per request, so it scales horizontally and needs no sticky sessions. Callers may send their own X-LLM-* headers; the server's model key is never spent on a caller's behalf.
Binds 127.0.0.1 by default and, on loopback, refuses requests whose Host or Origin is not local. Bind wider and put TLS in front: keys travel in headers.
docker build -t cob-rag-mcp . docker run --rm -p 127.0.0.1:3333:3333 \ -e COB_RAG_URL=http://host.docker.internal:8000 \ cob-rag-mcp
The engine URL must be reachable from the container: host.docker.internal for an engine on the host, or the engine's service name on a shared Docker network.
Command npx, arguments -y cob-rag-mcp start, plus the COB_RAG_* environment variables. With a global install, the command is simply cob-rag-mcp start.
If a client shows the server as failed, run npx -y cob-rag-mcp start in a terminal with the same environment: the reason is printed on stderr.
Each tool is one definition that is both an MCP tool and a CLI command. The server registers only the tools the key can use, and hides destructive ones unless allowed. With a tenant or admin key, tools that act on one corpus need a corpus_id (or a COB_RAG_CORPUS_ID default); a corpus key never sees that field.
Who the key is, and what the engine offers.
whoamiWhich kind of key this is and what it reaches
CLI: whoami · keys: any keyget_engine_infoEngine version, features, embedding and LLM models, limits (no secrets)
CLI: info · keys: any keyPassages with sources, or a cited answer.
searchRelevant passages with sources, no generation
CLI: search · keys: any keyaskA cited answer from the engine's model
CLI: ask · keys: any keylist_documentsDocuments, with record ids and metadata; search by file name or record id; paged
CLI: documents list · keys: any keyget_documentOne document, its versions and its indexed chunks, paged
CLI: documents get · keys: any keylist_document_versionsVersions of one document
CLI: documents versions · keys: any keydelete_documentdestructiveDelete a document, its versions and vectors
CLI: documents delete · keys: any keyadd_recordswriteAdd or update up to 1000 text records
CLI: ingest records · keys: any keyupload_filewriteUpload a local file; MCP: stdio only, inside COB_RAG_UPLOAD_DIR
CLI: ingest upload · keys: any keyget_ingest_jobOne ingest job: status, corpus, file, mode, and the documents a held upload resembles
CLI: ingest job · keys: any keylist_ingest_jobsIngest jobs in scope; filter by status and corpus_id; paged
CLI: ingest jobs · keys: any keyget_usageRequests, tokens and estimated cost, by day, corpus, tenant or source
CLI: usage · keys: any keylist_feedbackRatings of answers with their questions; filter by corpus, rating, time; paged
CLI: feedback list · keys: any keyA corpus's settings, and the engine's own.
get_corpus_settingsA corpus's model, prompt and retrieval settings
CLI: settings get · keys: any keyupdate_corpus_settingswriteChange prompt and retrieval settings; null clears one
CLI: settings update · keys: any keyget_assistantThe knowledge base's assistant: on or off, the published configuration and the draft
CLI: assistant get · keys: any keyupdate_assistant_draftwriteChange the assistant's draft with a JSON merge patch; nothing goes live until it is published
CLI: assistant draft · keys: any keypublish_assistantwriteMake the draft live on every channel; earlier versions stay restorable
CLI: assistant publish · keys: any keyget_settingsSign-up mode (open, approval, closed) and white-label branding, with who changed them last
CLI: engine settings · keys: admin onlyupdate_settingswriteChange the sign-up mode and/or branding; null resets a field
CLI: engine update-settings · keys: admin onlyA knowledge base is a corpus.
list_corporaCorpora in scope with owner, document and chunk counts, last activity; paged, or all
CLI: corpora list · keys: tenant or adminget_corpusOne corpus with its settings
CLI: corpora get · keys: tenant or admincreate_corpuswriteNew corpus, optionally with its embedding model; returns its ck_ key once
CLI: corpora create · keys: tenant or adminupdate_corpuswriteName, model, prompt, retrieval, embedding settings; admin can move it to another tenant
CLI: corpora update · keys: tenant or adminrotate_corpus_keydestructiveNew ck_ key; the old one stops working
CLI: corpora rotate-key · keys: tenant or admindelete_corpusdestructiveDelete a corpus and everything in it
CLI: corpora delete · keys: tenant or adminlist_migrationsEmbedding migrations across corpora (pending_approval ones included); paged
CLI: migrations list · keys: tenant or adminPublishable keys for a corpus's website widget.
list_widget_keysWebsite widget keys (pk_)
CLI: widget-keys list · keys: any keycreate_widget_keywriteNew widget key and embed snippet
CLI: widget-keys create · keys: any keyrevoke_widget_keydestructiveDelete a widget key
CLI: widget-keys revoke · keys: any keyWho the customers are, and what they may use.
get_my_tenantThis tenant key's own tenant: name, status, corpus count and limit
CLI: tenants me · keys: tenant onlyrotate_my_tenant_keydestructiveNew tk_ key for the key making the call; it stops working at once
CLI: tenants rotate-my-key · keys: tenant onlylist_tenantsTenants with status (pending sign-ups, active, suspended) and owners; paged
CLI: tenants list · keys: admin onlycreate_tenantwriteNew active tenant, optionally on a plan with its own knowledge-base limit; returns its tk_ key once
CLI: tenants create · keys: admin onlyrotate_tenant_keydestructiveNew tk_ key; the old one stops working
CLI: tenants rotate-key · keys: admin onlyactivate_tenantwriteActivate a pending sign-up (optional plan_id and note)
CLI: tenants activate · keys: admin onlysuspend_tenantdestructiveEvery key, widget and sign-in of the tenant stops (data kept); needs confirm_name
CLI: tenants suspend · keys: admin onlyreactivate_tenantwriteUndo a suspension
CLI: tenants reactivate · keys: admin onlydecline_tenantdestructiveRemove a pending sign-up and its account; the owner gets a polite e-mail
CLI: tenants decline · keys: admin onlydelete_tenantdestructiveDelete a tenant and everything it owns; needs confirm_name
CLI: tenants delete · keys: admin onlylist_plansPlans with their four limits and how many tenants use each
CLI: plans list · keys: admin onlyset_tenant_planwriteMove a tenant to another active plan
CLI: plans set · keys: admin onlyget_my_planA tenant's plan, limits and usage: questions this month (and when they reset), knowledge bases, documents, widget keys
CLI: plans usage · keys: tenant or adminA tenant's owners and members.
list_teamA tenant's owners and members (last sign-in) and open invitations
CLI: team list · keys: tenant or admininvite_memberwriteInvite someone as owner or member; the engine e-mails the link (never returned)
CLI: team invite · keys: tenant onlyadmin_invitewriteInvite someone to any tenant, typically its first owner; returns accept_url, the link to send them
CLI: team admin-invite · keys: admin onlyTool annotations match: readOnlyHint on reads, destructiveHint on destructive tools, openWorldHint: false everywhere, because every call goes to your own engine. --read-only leaves only the read tools. One prompt is included, answer-with-citations: search first, answer only from the passages, cite each source. Request and response shapes are typed from the engine's OpenAPI spec, so the tools cannot drift from the API. cob-rag-engine tools prints every tool and which keys can use it.
cob-rag-engine <command> [options]. Global options: --url, --key, --config, --json, --yes, --read-only. Every command has --help. Exit codes: 0 success, 1 engine or configuration error, 2 invalid input.
cob-rag-engine login --url http://127.0.0.1:8000 --key ck_... # Logged in to http://127.0.0.1:8000 with ck_****a1b2 # kind corpus # corpus_name acme-faq cob-rag-engine whoami cob-rag-engine config show # every setting, its source, secrets masked cob-rag-engine config get api_key # ck_****a1b2 cob-rag-engine config set corpus_id 7b221003-... cob-rag-engine config path
login checks the key with the engine's /api/v1/whoami before saving anything, and writes the config file owner-only (0600). Leave --key out at a terminal and it prompts without echoing.
cob-rag-engine search "How long should I fast before a cholesterol test?" --final-k 3 # [1] Fasting before a lipid profile [faq-fasting-lipid] (score 0.066) cob-rag-engine ask "Do I need to fast for a thyroid test?" # No, you do not need to fast for a thyroid test. ... [1] # # Sources: # [1] Thyroid test (TSH, T3, T4) [faq-thyroid] cob-rag-engine ask "..." --stream # prints as it is generated cob-rag-engine ask "..." --stream --json # raw events, one JSON object per line
search returns passages with sources and needs no model. ask returns a cited answer from the engine's model. Streaming is a CLI feature: an MCP tool call returns one result.
# FAQ entries, products or articles (JSON array or JSON lines), wait until indexed cob-rag-engine ingest records --records @faq.json --wait cob-rag-engine ingest upload ./price-list.pdf --wait cob-rag-engine ingest jobs --status pending_review cob-rag-engine ingest job <job id> cob-rag-engine documents list --search price cob-rag-engine documents get <document id> --chunk-limit 5
ingest records adds or updates up to 1000 text records. A held upload lists the documents it resembles.
cob-rag-engine usage --group-by source --start 2026-09-01 cob-rag-engine feedback list --max-rating 2 --start 2026-09-01 cob-rag-engine settings update --retrieval-config '{"final_k": 8}' cob-rag-engine settings update --retrieval-config '{"final_k": null}' # back to the default cob-rag-engine info # engine version, features, models, limits cob-rag-engine tools # every tool and which keys can use it cob-rag-engine documents list --json | jq '.items[].id'
Updates change only what you send. A field set to null is removed so the engine default applies again.
cob-rag-engine corpora create "pune-path-lab" --description "Test prep FAQ" cob-rag-engine corpora create "pune-path-lab" --tenant-id <tenant id> # admin names the tenant cob-rag-engine corpora list --all cob-rag-engine widget-keys create "Lab website" --corpus-id <id> \ --allowed-origins https://lab.example cob-rag-engine migrations list --status pending_approval cob-rag-engine corpora delete <id> # asks first; --yes to skip
Lists are paged by the engine. Under each table the CLI says which items these are and the option that gets the next page.
cob-rag-engine plans list cob-rag-engine tenants activate <tenant id> --plan-id <plan id> --note "paid via UPI" cob-rag-engine team admin-invite <tenant id> owner@shree.example cob-rag-engine plans usage --tenant-id <tenant id> cob-rag-engine engine update-settings --signup-mode approval \ --branding '{"product_name": "Sahayak AI"}'
team admin-invite prints the link to send the customer's first owner.
cob-rag-engine plans usage # questions this month, and when they reset cob-rag-engine team list cob-rag-engine team invite ravi@shree.example --role member cob-rag-engine tenants me cob-rag-engine tenants rotate-my-key # warns, asks, then offers to save the new key cob-rag-engine tenants rotate-my-key --yes --save-key # scripts: rotate and save in one go
tenants rotate-my-key replaces the very key the CLI is using, and the old key fails on its next request. The CLI says so before asking.
The server asks the engine who the key is and offers only the tools that key can use. The engine enforces scope on every request; this package also hides what a key cannot use, so an agent is not tempted to try.
| Key | Prefix | What it reaches | Give it to an agent? |
|---|---|---|---|
| Corpus key | ck_ | One knowledge base and nothing else: search, ask, documents, ingest, settings, usage, feedback, widget keys. | Yes, this is the default. A corpus key for one knowledge base. |
| Tenant key | tk_ | Manages that tenant's corpora, its team, its own plan and record. Can rotate its own key. | Only when the agent must create or manage corpora. |
| Admin key | RAG_ADMIN_API_KEY | Runs the engine: tenants, plans, sign-up mode and branding, every corpus. | Almost never. |
ck_Hand the agent the corpus key for the one knowledge base it works on, add --read-only if it should only look things up, and leave destructive tools off.
create_corpus, create_tenant and every rotate_* return the new key in the tool result, because that is the only time the engine reveals it.
pk_ is a different thingWidget keys (list_widget_keys, create_widget_key, revoke_widget_key) are for a corpus's website widget, and come with an embed snippet.
From the README and SECURITY.md.
config show, login and every log line mask keys (ck_****a1b2).COB_RAG_ALLOW_DESTRUCTIVE=true. The CLI asks before each one, and refuses when it cannot ask unless you pass --yes.--read-only or COB_RAG_READ_ONLY=true hides every write tool from MCP clients and makes the CLI refuse every write.upload_file exists over MCP only on stdio and only when COB_RAG_UPLOAD_DIR is set. Paths are resolved, symlinks included, and anything outside that directory is refused, so a prompt-injected agent cannot ship your SSH keys into a knowledge base. Use a dedicated folder, never your home directory.127.0.0.1 bind, or put TLS and a firewall in front of it. Leave COB_RAG_HTTP_USE_SERVER_KEY off unless every client that can reach the port should act with that key.rotate_my_tenant_key cuts off the key in useThe server's own key is dead the moment it succeeds; restart it with the new key. The CLI warns first and offers to save the new key.cob-rag-engine login, which prompts without echo, or your MCP client's secret inputs, over pasting keys into files.