How do I use senza-knowledge-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@senza-knowledge-mcp What's our documented process for rotating API keys? Include citations." That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

senza-knowledge-mcp

by oh-my-harness

Overview Schema Source Related Servers Discussions Admin

Python

Local

senza-knowledge-mcp

Team domain knowledge base — MCP-first service built on Senza.

Coding agents (Claude Code, oh-my-pi, any MCP client) query your team's domain documents through MCP; a built-in Senza agent searches and synthesizes grounded, citation-backed answers. A lightweight admin web handles document ingestion and browsing.

How it works

coding agent (MCP client) ──MCP stdio──► senza-knowledge-mcp
                                            ├─ kb_ask    ask a question → grounded answer w/ citations
                                            ├─ kb_search semantic search → source + snippet
                                            ├─ kb_get    fetch full document (fast, no LLM)
                                            └─ kb_list   list knowledge base contents
                                            (kb_ask / kb_search run an internal Senza agent
                                             with the base knowledge plugin)

admin web settings page ──► ~/.senza-knowledge-mcp/config.json (shared config)

browser ──► admin web (FastAPI)            upload PDF/text → parse → raw store

Data model: an immutable raw layer (documents / documents+images, parsed with Docling; pluggable backend — swap in a cloud MinerU service later) + derived layers. Images are understood on use by a multimodal model, not at ingest time.

Related MCP server: mcp-business-bot

Install

Requires Python 3.12+.

git clone https://github.com/oh-my-harness/senza-knowledge-mcp.git
cd senza-knowledge-mcp
uv sync --extra dev        # or: pip install -e . (runtime deps only)

No provider configuration ships with the source — the source binds to no provider. Configure once, in either of two ways:

Admin web (recommended): start the admin web → open Settings → pick Provider (openai or anthropic) → fill in API key / Base URL / Model → Save. Persisted to ~/.senza-knowledge-mcp/config.json.
Environment variables: SENZA_KB_PROVIDER (openai | anthropic), SENZA_KB_API_KEY, SENZA_KB_BASE_URL, SENZA_KB_MODEL (all four required; env takes precedence over the config file).

kb_ask / kb_search need the LLM; kb_get / kb_list are pure data tools and work without any configuration.

Quick start

1. Start the admin web (configuration + document ingestion):

python -m senza_knowledge_mcp.admin_app
# open http://127.0.0.1:8081 → Settings: fill API key / Base URL / Model → Save

2. Ingest documents: admin web → Upload → pick a PDF or UTF-8 text/markdown file. The document is parsed and stored in the raw layer, ready to be searched.

3. Wire the MCP server into your coding agent (see next section) and start asking.

Wire it into your coding agent

oh-my-pi (.omp/mcp.json, project level):

{
  "mcpServers": {
    "kb": {
      "type": "stdio",
      "command": "/abs/path/to/senza-knowledge-mcp/.venv/bin/python",
      "args": ["-m", "senza_knowledge_mcp.mcp_server"],
      "env": { "SENZA_KB_RAW_DIR": "/abs/path/to/kb/raw" }
    }
  }
}

Any other MCP client works the same way — the server speaks standard MCP over stdio with four tools: kb_ask, kb_search, kb_get, kb_list.

Tools

Tool	Kind	What it does
`kb_ask(question)`	smart, ~10s	internal agent searches + synthesizes a cited answer
`kb_search(query)`	smart	semantic search → source identification + snippets
`kb_get(doc)`	fast, ms	full markdown of a document by `source_id` or file name
`kb_list()`	fast, ms	all documents in the knowledge base

Fast tools read the immutable raw layer directly — no LLM involved, no timeouts. Smart tools run the internal Senza agent through whichever provider you configure (Anthropic or OpenAI-compatible).

Configuration

Env var	Required	Meaning
`SENZA_KB_PROVIDER`	yes	`openai` (OpenAI-compatible: DeepSeek, GLM, SiliconFlow, ...) or `anthropic`
`SENZA_KB_API_KEY`	yes	provider API key
`SENZA_KB_BASE_URL`	yes	provider endpoint
`SENZA_KB_MODEL`	yes	model id (e.g. `deepseek-v4-flash`, `claude-sonnet-4-5`)
`SENZA_KB_RAW_DIR`	no (default `.`)	raw layer directory
`SENZA_KB_DOMAINS`	no	comma-separated domain tags

Milestones

✅ M0 scaffold · M1 ingest pipeline (Docling → raw layer) · M3 MCP service · M4 admin web
Planned: M5 relation layer (heartbeat agent) · M6 distilled knowledge pages + llm-wiki write-back · M7 cloud MinerU parser (swap-in via the parser abstraction) · M8 phase-2 shared knowledge base (single cloud instance, MCP over HTTP, multi-user permissions via the base KnowledgeAccessControl)

License

MIT

Available Tools

4 tools

kb_askA

Answer a question grounded in the domain knowledge base (uses an internal agent to search and synthesize; may take ~10s).

ParametersJSON Schema

Name	Required	Description	Default
`question`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses meaningful behavioral detail: an internal agent performs search and synthesis, and the call may take ~10s, which helps with tool selection and timeout expectations. Since no annotations are provided, this adds real context, though it does not cover failure cases such as what happens when the KB lacks an answer.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is one tight sentence with the core action front-loaded and the latency/mechanism note set off in parentheses. There is no filler or repetition; every clause contributes useful information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple, has only one required string parameter, and an output schema exists, so the description does not need to explain return values. It covers purpose, mechanism, and latency, but lacks explicit routing guidance relative to sibling tools, which is a minor completeness gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description only implicitly defines the single 'question' parameter as the query to be answered from the KB. It adds minimal semantic detail beyond the property name, but the parameter is self-evident enough that the lack of explicit format, length, or example guidance is not a major gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('answer') and resource ('domain knowledge base'), and the parenthetical clarifies that it synthesizes via an internal agent. It positions the tool as a grounded Q&A tool distinct from the retrieval-style siblings, though it does not explicitly contrast with kb_search, kb_get, or kb_list.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies this tool is for natural-language questions that need a synthesized answer, but it never explicitly states when to choose kb_ask over kb_search/kb_get/kb_list or when not to use it. No exclusions or alternative conditions are provided, leaving the routing decision to the agent's inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

kb_getB

Fetch the full markdown of a knowledge document by source_id or file name (fast, no LLM involved).

ParametersJSON Schema

Name	Required	Description	Default
`doc`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

B3.3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It states the tool returns the full markdown of a document, which is the primary behaviornovel. It notes it is 'fast, no LLM involved,' which is useful context. However, it does not disclose potential side effects (none expected for a get), error behavior, or performance characteristics beyond speed. It is adequate but not comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that immediately states the purpose and key constraint. It is front-loaded with the verb 'Fetch' and resource. It avoids fluff and is highly efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with one parameter, and the description explains the parameter's domain and the output type (markdown). There is no output schema beyond the tool's own, so the description doesn't need to detail return values. However, it lacks information on error cases (e.g., document not found) and the exact format of the 'doc' identifier. It is complete enough for a basic call but not deeply robust.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has one parameter 'doc' with no description, and the description covers 0% of the schema. The description elaborates on what the parameter accepts (source_id or file name) but does not explain the format, required syntax, or examples. This is a partial improvement over the schema, which is empty, but it's insufficient for unambiguous use.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool fetches the full markdown of a knowledge document, specifying the identifier (source_id or file name). It distinguishes this from siblings like kb_ask and kb_search by emphasizing 'full markdown' and 'no LLM involved,' which is specific. However, it doesn't explicitly name the sibling tools it differs from, but the purpose is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is for direct retrieval by identifier, contrasting with search/ask tools that may involve LLM or querying. However, it does not explicitly state when to use this over kb_search or kb_ask, nor does it mention any exclusions or conditions. The phrase 'no LLM involved' hints at use cases but is not explicit guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

kb_listA

List all documents in the knowledge base (source_id, name, size, dates).

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full responsibility for behavioral disclosure. It states the action ('List all documents') which implies a read-only operation, but it does not mention pagination, ordering, size limits, or any edge cases like hidden or deleted documents. For a simple list tool this is adequate, but it does not add context beyond the action itself.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence that conveys the entire purpose with zero fluff. Every word earns its place, and the output fields are listed compactly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values are already defined. The description covers the action and scope completely for a list-all tool. There is no missing information an agent would need to decide whether to call it or interpret its result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the schema is trivially complete (100% coverage). The description adds no parameter-specific meaning because none exist, and none is needed. This meets the baseline for a parameterless tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('List') and resource ('documents in the knowledge base'), and enumerates the returned fields (source_id, name, size, dates). This clearly distinguishes it from siblings like kb_search (find) and kb_get (retrieve a single document), leaving no ambiguity about its purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage: call this when you want a complete inventory of documents. However, it does not explicitly exclude alternatives or mention when to prefer kb_search or kb_get, so it lacks explicit when-not guidance. The sibling names make the distinction fairly obvious, but the description itself does not spell it out.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

kb_searchA

Search the knowledge base (semantic, via internal agent); returns matching source identification + snippets. Use kb_get to fetch full text.

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No
`query`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses that the search is semantic and via an internal agent, which hints at potential latency or indirect execution but does not elaborate. It also mentions it returns 'source identification + snippets,' which is useful. However, it omits details like result ranking, pagination, or errors, which is a gap given no annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with no fluff. It front-loads the core function (search, semantic, internal agent) and immediately tells the user what it returns, followed by a pointer to the alternative. Every word contributes.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that the tool has only 2 parameters (one required) and no complex nested objects, the description covers the essential purpose and return type. The presence of an output schema helps, though it isn't shown in the description. The main missing piece is parameter semantics, but for a simple search tool, the overall context is fairly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must explain the parameters, but it does not mention query or limit at all. The schema itself provides basic types but not semantics; the description adds no value beyond what the schema shows identity-wise. The description's mention of returning snippets implies query is used for search, but it doesn't clarify limit's role (e.g., max results) or default behavior, leaving the agent to infer. This is a moderate gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool searches the knowledge base semantically via an internal agent and returns source identification plus snippets. It distinguishes itself from kb_get (for fetching full text) and implies its use for finding relevant content, making its purpose unambiguous and distinct from siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says to use kb_get to fetch full text, which provides a clear alternative for when more detail is needed. However, it does not mention when to prefer kb_ask or kb_list, leaving some ambiguity in distinguishing from those siblings, but the primary routing (search vs. fetch) is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

4 tool updatesv0.1.0Sep 15, 2026
- First observedkb_ask
- First observedkb_get
- First observedkb_list
- First observedkb_search

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.1/5.0

Scored 2026-09-15 17:45 across 4 tools

Disambiguation5/5

kb_list, kb_search, kb_get, and kb_ask each target a distinct user intent: catalog browsing, source retrieval, full-text fetching, and synthesized answering. The only close pair, kb_ask vs kb_search, is clearly disambiguated by their outputs: an answer versus source snippets.

Naming Consistency5/5

All tools follow a uniform kb_<verb> pattern with simple, clear verbs. There are no mixed conventions or vague names.

Tool Count5/5

Four tools is appropriate for a focused read-only knowledge base server. Each tool covers one core operation and none feel redundant or missing.

Completeness5/5

The read-side lifecycle is complete: list, search, get, and ask cover discovery through consumption. Write/management operations are absent, but they appear outside the server's intended purpose.

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

Knowa
com.knowalabs
Team docs served to AI agents over MCP - search, Markdown reads, version pinning, read audit.
Documentation Access Knowledge & Memory Search
2
iknowOAuth
dev.iknow
Knowledge base MCP for AI agents on iknow.dev. Search, read, and maintain via OAuth.
Knowledge & Memory Search Documentation Access
1
WitWikiOAuth
app.witwiki
A shared team wiki your coding agents read and write — across every repo and every MCP client.
Workplace & Productivity Knowledge & Memory Note Taking
1
docs2mcpOAuth
com.docs2mcp
Query your own PDFs and documents from any MCP client. Every answer cites the page it came from.
RAG Systems Search
1

Related MCP Servers

expert-mcp-server
Knowledge & Memory Search
benthomasson
A
license
A
quality
D
maintenance
Enables MCP-compatible agents to query beliefs, search documents, and explore reasoning chains from expert-service knowledge bases.
Updated 3 months ago (2026-06-12 19:30 UTC)
10
MIT
mcp-business-bot
RAG Systems Knowledge & Memory
Akes102
F
license
Not graded
quality
C
maintenance
Enables querying company knowledge base using RAG, providing accurate answers from internal documents via MCP.
Updated 2 months ago (2026-07-13 07:18 UTC)
-
shared-docs-mcp
RAG Systems Knowledge & Memory Documentation Access
yashpapa6969
F
license
Not graded
quality
B
maintenance
MCP server for a shared Postgres-backed knowledge base with hybrid retrieval and agentic RAG, enabling coding agents to upload, search, and ask questions over documents with cited answers.
Updated a month ago (2026-08-10 14:18 UTC)
-
mcp-rag-bridge
RAG Systems Search Vector Databases
zyay
A
license
Not graded
quality
B
maintenance
Enables AI agents to query and manage a document knowledge base via MCP, with RAG-powered search and grounded answers with citations.
Updated a month ago (2026-08-11 18:19 UTC)
MIT