MCP Server - Aigmented

The Aigmented MCP server lets you search, navigate, and pull content from your knowledge base directly inside Claude Desktop, Cursor, LibreChat, or any MCP-compatible client. As of this release, the MCP server exposes the same data primitives that Aigmented’s internal auto-wiki uses to build content — so your external agent (Claude, Cursor, etc.) can explore the knowledge graph, pull topic-scoped card sets, and synthesize its own documents, briefs, or training materials.

The MCP package @aigmented/mcp is not yet published to npm. For now, use the source build from the repository.

Setup for Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "aigmented": {
      "command": "npx",
      "args": ["@aigmented/mcp"],
      "env": {
        "AIGMENTED_API_KEY": "sk-YOUR_API_KEY",
        "AIGMENTED_COLLECTION_ID": "49"
      }
    }
  }
}

Setup for Cursor

Add to Cursor’s MCP settings:

{
  "aigmented": {
    "command": "npx",
    "args": ["@aigmented/mcp"],
    "env": {
      "AIGMENTED_API_KEY": "sk-YOUR_API_KEY",
      "AIGMENTED_COLLECTION_ID": "49"
    }
  }
}

Environment variables

Variable	Required	Default	Description
`AIGMENTED_API_KEY`	Yes	—	Your API key (`sk-...`)
`AIGMENTED_API_URL`	No	`https://aigmented.io`	API base URL
`AIGMENTED_COLLECTION_ID`	No	—	Default collection ID (if omitted, specify per-tool call)

Available tools

Thirteen tools are exposed by the MCP server, split into four groups.

Discovery & Q&A

`list_collections`

List all available knowledge collections. No parameters.

`search_knowledge`

Semantic search over the knowledge base.

Parameter	Required	Description
`query`	Yes	Search query
`collection_id`	No	Collection ID (uses default if omitted)
`top_k`	No	Max results (default 5)

`ask_question`

Ask a question and get an AI-generated answer with citations.

Parameter	Required	Description
`question`	Yes	Your question
`collection_id`	No	Collection ID (uses default if omitted)

`get_card_details`

Fetch full contents of a card with complete source provenance. Use this when you need to cite where information came from.

Parameter	Required	Description
`card_id`	Yes	Card ID (from search or retrieval results)

Response includes:

card_id, title, statement, knowledge_type, importance_score
source_documents — array of {id, name} for every document the card was generated from
page_numbers — flat array of all source page numbers (across all docs; the schema doesn’t track per-doc page mapping)
section_context — section path inside the source document (e.g. "Chapter 3 / Vacations")
related_header — nearest header in the source document
verbatim_content — exact quote from the source, when applicable (forms, templates, legal text)
source_card_ids — Phase 2 intermediate cards (deeper traceability)
related_card_ids — up to 5 graph-derived neighbors (empty if no graph)
created_at, updated_at

Also kept for backwards compatibility: source_document (the first entry of source_documents plus a page_range like "12-14"). These tools require that the collection has a built knowledge graph. Collections without a graph will return a 409 error with a guiding message — use retrieve_for_topic or search_knowledge instead.

`describe_collection`

Returns collection statistics, graph-built flag, and a preview of top clusters. Call this first to understand what’s available before running more expensive tools.

Parameter	Required	Description
`collection_id`	No	Collection ID (uses default if omitted)

Returns: { total_cards, has_graph, total_clusters, total_entities, top_clusters }.

`list_clusters`

Lists all knowledge graph clusters (topics / communities) in a collection. Each cluster contains: id, llm_name, llm_description, card_count, and up to 5 top_entities. Use this to get a structured view of “what topics exist in this collection”.

`get_cluster`

Full detail of a single cluster: cards (with 200-character previews), entities, and related clusters.

Parameter	Required	Description
`cluster_id`	Yes	Cluster ID (from `list_clusters`)
`collection_id`	No	Collection ID (uses default if omitted)

`list_entities`

Top entities (people, organizations, concepts) in the collection, with card counts.

Parameter	Required	Description
`top_k`	No	Max results (default 50, max 200)
`entity_type`	No	Filter by type (e.g., `PERSON`, `ORG`, `CONCEPT`)
`collection_id`	No	Collection ID (uses default if omitted)

`get_gaps`

Knowledge gaps: isolated entities (appearing in only one card with few relations) and undersized clusters. Useful for identifying coverage problems before generating content.

Content retrieval

`retrieve_for_topic`

The key tool for content creation. Runs the same retrieval pipeline that Aigmented’s auto-wiki uses internally: embedding search → importance filter → deduplication → Cohere reranking. Returns the most relevant cards for a given topic, ready to feed into your agent’s synthesis step.

Parameter	Required	Description
`topic`	Yes	Topic or section title
`description`	No	Longer description of what you’re looking for (improves retrieval)
`top_k`	No	Max cards to return (default 25, max 50)
`rerank`	No	Run Cohere rerank (default `true`)
`min_importance`	No	Filter cards below this importance score (default `0.4`)
`collection_id`	No	Collection ID (uses default if omitted)

Returns cards as { card_id, title, statement, importance_score, knowledge_type }.

Card-level browsing

Use these when you want to enumerate, bulk-fetch, or explore semantic neighborhoods of individual cards — without going through the retrieval pipeline.

`list_collection_cards`

Flat paginated browse of all cards in a collection. No query needed. Useful for “show me what’s in this collection” overviews.

Parameter	Required	Description
`offset`	No	Pagination offset (default 0)
`limit`	No	Max cards per page (default 20, max 100)
`knowledge_type`	No	Filter by type (e.g. `fact`, `procedure`, `decision`)
`cluster_id`	No	Filter by graph cluster (requires built graph)
`collection_id`	No	Collection ID (uses default if omitted)

Returns: { cards: [{card_id, title, statement, knowledge_type, importance_score}], total_count, offset, limit, has_more }. Statement truncated to 200 chars — call get_card_details for full content.

`get_cards_batch`

Fetch full details of multiple cards in one call (up to 25 IDs). Use after search_knowledge / retrieve_for_topic when you need full content of several cards — avoids N round-trips.

Parameter	Required	Description
`card_ids`	Yes	Array of card IDs, length 1-25
`collection_id`	No	Collection ID (uses default if omitted)

Returns: { cards: [...], not_found: [ids] }.

`get_related_cards`

Find cards semantically similar to a given card. Use to build topical clusters around a single card (e.g. for quiz generation: “5 cards most related to card X”).

Parameter	Required	Description
`card_id`	Yes	Source card ID
`limit`	No	Max related cards (default 5, max 20)
`collection_id`	No	Collection ID (uses default if omitted)

Returns: { source_card_id, related: [{card_id, title, statement, similarity_score}] }. Does not require a graph.

Building content with MCP — a cookbook

The new tools let your agent replicate what Aigmented’s auto-wiki does internally — navigating the graph and pulling topic-scoped sources — while keeping synthesis in your agent’s hands. Some common patterns:

1. “Summarize what we know about X”

1. retrieve_for_topic(topic="X", top_k=20)
2. Agent reads the cards and writes a summary.

No graph needed. Works on any collection with search enabled.

2. “Generate a training section on onboarding”

describe_collection()               # confirm graph is built
list_clusters()                     # see all topics
get_cluster(cluster_id=<onboarding>)  # cards + entities in that cluster
retrieve_for_topic(topic="Onboarding for new hires", description="...", top_k=30)
Agent synthesizes using cards from steps 3 and 4 as source material.

3. “What people appear in our knowledge base?“

list_entities(entity_type="PERSON", top_k=100)
For each person of interest: retrieve_for_topic(topic=<person name>, top_k=10)
Agent builds a profile page per person.

4. “Where are our knowledge gaps?“

1. get_gaps()
2. Agent reports isolated entities and undersized topics — feeds back to a human reviewer or drives which documents to ingest next.

5. “Build a quiz around this specific card”

get_related_cards(card_id=<seed card>, limit=10)
get_cards_batch(card_ids=[...related IDs...])
Agent generates 5 questions + answers citing the source cards.

6. “Browse all cards in a collection and pick what’s relevant”

describe_collection()                              # orient the agent
list_collection_cards(offset=0, limit=50)          # first page of lightweight summaries
list_collection_cards(offset=50, limit=50)         # continue
Agent picks IDs of interest → get_cards_batch([...])

This is the flow for an admin building a learning program — see what’s available, cherry-pick sources, assemble content.

Tips

Always start with describe_collection on a fresh collection. It tells your agent whether graph tools are available and gives an at-a-glance map of topics.
Prefer retrieve_for_topic over search_knowledge for content generation — it runs the fuller pipeline (importance filter + dedup + rerank) that produces cleaner source sets.
get_card_details is cheap — once your agent has a card_id from any other tool, pulling the full card is lightweight.
Cost note: retrieve_for_topic uses Cohere embedding + reranking (paid). Default top_k=25 is a good balance. Setting rerank=false skips the rerank if you’re cost-sensitive.

HTTP mode (LibreChat)

For LibreChat or other HTTP-based MCP clients, run the HTTP server:

AIGMENTED_API_KEY=sk-YOUR_KEY npx @aigmented/mcp --http

This starts an HTTP server on port 3002 (configurable via MCP_PORT) with the MCP Streamable HTTP transport at /mcp.

Errors and degradation

Scenario	What happens	What to do
Collection has no graph built	Graph tools return 409	Use `retrieve_for_topic` / `search_knowledge` instead, or run `build-graphs` on the collection
`top_k > 50` on `retrieve_for_topic`	400 validation error	Lower `top_k`
`limit > 100` on `list_collection_cards`	400	Lower `limit`
`card_ids > 25` on `get_cards_batch`	400	Split into multiple batches
`get_related_cards` with missing `card_id`	404	Verify the ID exists in the collection
Invalid / cross-team `collection_id`	404	Check the ID and that the API key belongs to the right team
Token quota exceeded	429	Wait for quota reset or request a higher limit

Documentation Index

​Setup for Claude Desktop

​Setup for Cursor

​Environment variables

​Available tools

​Discovery & Q&A

​list_collections

​search_knowledge

​ask_question

​get_card_details

​Knowledge graph navigation

​describe_collection

​list_clusters

​get_cluster

​list_entities

​get_gaps

​Content retrieval

​retrieve_for_topic

​Card-level browsing

​list_collection_cards

​get_cards_batch

​get_related_cards

​Building content with MCP — a cookbook

​1. “Summarize what we know about X”

​2. “Generate a training section on onboarding”

​3. “What people appear in our knowledge base?“

​4. “Where are our knowledge gaps?“

​5. “Build a quiz around this specific card”

​6. “Browse all cards in a collection and pick what’s relevant”

​Tips

​HTTP mode (LibreChat)

​Errors and degradation

Setup for Claude Desktop

Setup for Cursor

Environment variables

Available tools

Discovery & Q&A

`list_collections`

`search_knowledge`

`ask_question`

`get_card_details`

Knowledge graph navigation

`describe_collection`

`list_clusters`

`get_cluster`

`list_entities`

`get_gaps`

Content retrieval

`retrieve_for_topic`

Card-level browsing

`list_collection_cards`

`get_cards_batch`

`get_related_cards`

Building content with MCP — a cookbook

1. “Summarize what we know about X”

2. “Generate a training section on onboarding”

3. “What people appear in our knowledge base?“

4. “Where are our knowledge gaps?“

5. “Build a quiz around this specific card”

6. “Browse all cards in a collection and pick what’s relevant”

Tips

HTTP mode (LibreChat)

Errors and degradation