Using the WorkingAgents Knowledge Base with Claude Code

When you connect Claude Code to a WorkingAgents MCP server, your AI agent gets access to a scoped knowledge base – your company’s internal documents, searchable by meaning or keyword, filtered by role permissions, and organized with tags. This guide shows how to actually use it in practice.

Setup

Claude Code connects to WorkingAgents as a remote MCP server. Once connected, the knowledge tools appear alongside all other WorkingAgents tools. No additional configuration is needed – your permissions determine which documents you can see.

To verify the connection, ask Claude Code:

> search the knowledge base for "onboarding"

If it returns results (or an empty list), the connection is working. If it returns an authorization error, your user account needs the Knowledge permission.

The Tools

Eight tools are available through the MCP connection:

Tool	What it does
knowledge_search	Semantic search – finds documents by meaning
knowledge_search_text	Keyword search – finds documents by exact terms
knowledge_add	Create a new document
knowledge_import	Import a markdown file
knowledge_update	Change tags, scope, visibility, or status
knowledge_list	List documents you can see
knowledge_get	Read a full document by ID
knowledge_delete	Remove a document (soft delete)

You don’t call these tools directly. You talk to Claude Code in plain English and it picks the right tool.

Searching

Semantic Search (by meaning)

Ask questions naturally. Claude Code uses knowledge_search to find documents that match the meaning of your question, even if the exact words don’t appear.

> do we have any documentation about how permissions work?

> what's our policy on remote work?

> find documents about deploying to production

> search knowledge base for anything about HIPAA compliance

Semantic search is best when you don’t know the exact terms used in the document. “How do we fire someone” will match a document titled “Employee Termination Procedures.”

Keyword Search (by exact terms)

When you know the specific term, name, or phrase you’re looking for, Claude Code uses knowledge_search_text for instant results without needing an embedding API call.

> search knowledge for "Santiago Pastorino"

> find documents mentioning "SOC 2"

> keyword search for "MCP gateway"

Filtering by Tags

Both search tools support tag filtering. Tags use AND logic – all specified tags must be present.

> search knowledge for deployment guides tagged "devops"

> find documents tagged "mcp" and "security"

> search for onboarding docs tagged "guide"

Search-Then-Read Workflow

Search results return chunks (~2000 characters), not full documents. When a chunk looks relevant but you need more context:

> search knowledge for "pricing strategy"

[Claude returns chunks with doc_id values]

> get the full document for that pricing strategy doc

[Claude calls knowledge_get with the doc_id]

This two-step pattern is the most common workflow. Search finds relevant chunks. Get retrieves the complete document.

Adding Documents

Quick Add

Tell Claude Code what you want to store and where it belongs:

> add this to the engineering knowledge base:
> "## Elixir Deployment Checklist
> 1. Run mix test
> 2. Check for compiler warnings
> 3. Deploy to staging first
> 4. Run smoke tests
> 5. Deploy to production"

> add a sales document titled "Pricing Tiers" with content about our three plans

> save this HR policy about vacation days to the knowledge base

Claude Code figures out the scope from context. If it’s ambiguous, it asks.

Adding with Tags

Specify tags when adding documents so they’re easier to find later:

> add this deployment runbook to engineering knowledge, tag it with "devops" and "runbook"

> save this as a general document tagged "onboarding" and "guide":
> [paste your content]

Adding Private Documents

Private documents are only visible to you, not to other users with the same scope permission:

> add this as a private engineering note:
> "Ideas for refactoring the auth module..."

> save my personal meeting notes to the knowledge base, make them private

Importing Markdown Files

If you have an existing markdown file, Claude Code can import it. The title is extracted from the first # heading:

> import the file asset/docs/access_control.md into engineering knowledge

> import this markdown as a sales document tagged "playbook":
> [paste markdown content]

Updating Documents

Tagging Existing Documents

Add or change tags on documents that are already in the knowledge base:

> list all knowledge documents

[Claude returns a list with IDs]

> tag document 42 with "mcp", "security", and "guide"

> add the tag "deprecated" to document 37

Note: knowledge_update replaces all tags, it doesn’t append. If a document has tags ["guide"] and you update with ["mcp"], it will only have ["mcp"]. To add a tag, include all existing tags plus the new one.

Changing Scope

Move a document to a different scope:

> move document 42 from general to engineering scope

Archiving

Archive documents instead of deleting them. Archived docs don’t appear in search or listings but remain in the database:

> archive document 42

> mark the old deployment guide as archived

Making Documents Private or Shared

> make document 42 private

> change document 37 to shared visibility

Listing and Browsing

List All Documents

> list all knowledge base documents

> show me what's in the knowledge base

> how many documents are in the knowledge base?

List by Tags

> list all documents tagged "guide"

> show me engineering documents tagged "devops"

> what documents are tagged "mcp" and "security"?

Real-World Scenarios

Building a Knowledge Base from Scratch

You’re starting with an empty knowledge base and want to populate it from existing documentation:

> read asset/docs/access_control.md and import it to engineering knowledge,
> tag it "access-control" and "security"

> read asset/docs/APPLICATION.md and import it to engineering knowledge,
> tag it "architecture" and "reference"

> add a general document titled "Company Overview" with this content:
> [paste content]
> tag it "about" and "onboarding"

Answering Questions from Internal Docs

The most common use case. A team member asks a question and Claude Code searches the knowledge base before answering:

> how do we handle HIPAA compliance for AI agents?

[Claude searches knowledge base, finds relevant docs, answers with citations]
"Based on the document 'AI Governance Compliance Guide', WorkingAgents handles
HIPAA compliance through three mechanisms: ..."

Maintaining Documentation

Periodically review and update the knowledge base:

> list all knowledge documents tagged "deprecated"

> archive documents 12, 15, and 23

> search for documents about the old auth system -- we need to update them

> update document 42 with tags "needs-review" and "stale"

Onboarding a New Team Member

Create a curated set of documents for new hires:

> list all documents tagged "onboarding"

> add a general document titled "First Week Checklist" tagged "onboarding" and "guide":
> [paste checklist content]

> search knowledge for "development environment setup"

Cross-Team Knowledge Sharing

A sales person needs technical context for a client meeting:

> search knowledge for "MCP access control" -- I need to explain our
> security model to a client

[Claude finds engineering docs the sales user has permission to see via
general scope, but not internal engineering-only docs]

Tips

Search first, always. Before answering questions about internal processes, policies, or products, search the knowledge base. It takes one second and prevents hallucinated answers.

Use semantic search for questions, keyword search for names. “How do we deploy?” works best with semantic search. “Santiago Pastorino” works best with keyword search.

Tag consistently. Pick a tagging convention and stick with it. Good patterns: type tags (guide, runbook, policy), domain tags (mcp, devops, security), and status tags (draft, reviewed, deprecated).

Chunk awareness. Search returns chunks, not full documents. A document might have 5 chunks. If the first chunk answers your question, great. If not, get the full document by ID.

Scope = access control, tags = organization. Scopes determine who can see a document. Tags determine how you find it. A document can be scope: engineering (only engineers see it) with tags: ["mcp", "guide"] (findable by topic).

Private documents are personal notes. Use private visibility for draft ideas, meeting notes, or work-in-progress content you’re not ready to share.