crowdsmart-mcp
This MCP server connects an MCP client to CrowdSmart to manage Knowledge Agents, run Jams of Knowledge Agents, and build/forecast/score Knowledge Model Agents.
Knowledge Agents: list communities and agents; create/update agents; set visibility; ask questions with citations and confidence; upload/add/list/read/status/delete documents; check corpus quality.
Jams: list/get Jams; create draft Jams with prompts, agents, and invitees; launch them; add agents; view results, participation, probabilities, top ideas, responses, and citations.
KMAs: list/create domains; add/resolve cases; create/attach/enable KMAs; list/read/review/tag documents; check preflight; start and follow staged builds; get/freeze forecasts; score; manage switches, needs, and cohorts.
Operations: uses a CrowdSmart API key, supports a configurable API URL, and marks tools as reads, adds, replaces/deletes, or queues background model work.
Scope limits: does not cover other platform areas such as person participation in Jams, Jam analytics/exports, schedules, KMA Jams/refits/revisions, or Track and runs.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@crowdsmart-mcp Ask my Knowledge Agent about the Q3 report and show its 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.
crowdsmart-mcp
An MCP server for CrowdSmart. It connects an MCP client (for example Claude Desktop, Claude Code, Cursor or Hermes) to the CrowdSmart research platform (csgcip). It authenticates with your own CrowdSmart API key.
The server has 51 tools. They cover three workflows:
Knowledge Agents that answer questions from their documents.
Jams in which Knowledge Agents discuss a topic.
Knowledge Model Agents (KMAs) that forecast the cases of a domain.
The server does not cover the rest of the platform. See Scope.
Tools
Each tool tells the client what it does to your CrowdSmart data (MCP tool annotations):
Effect | Meaning |
Reads | Changes nothing |
Adds | Adds a record, for example a document or a Jam |
Replaces | Replaces or deletes settings, a document, a review, a case profile value or a build |
Queues | Changes nothing that you see, but can queue model calls on CrowdSmart's worker. A repeated call queues nothing new |
Knowledge Agents
A Knowledge Agent answers questions from its own documents.
Tool | What it does | Effect |
| Lists your communities and your default community. A new agent or Jam goes into a community | Reads |
| Lists the members of a public community, or of a private one you belong to, with their roles and emails. Knowledge Agents shared with the community are not members | Reads |
| Lists your agents and the agents shared with you | Reads |
| Creates a private agent with no documents | Adds |
| Changes the name, headline, instructions or mode of your agent | Replaces |
| Sets who can ask your agent | Replaces |
| Asks an agent a question. The answer cites the agent's documents and has a confidence score. With | Adds the question to the agent's query history |
| Lists the documents of an agent | Reads |
| Returns the text of a document, for example to check a citation | Reads |
| Uploads a file from this computer to your agent, then waits for its text | Adds |
| Shows whether the text of an uploaded document is ready, or why it failed | Reads |
| Adds text with its source (URL, author, date) to your agent | Adds |
| Deletes a document from your agent. You cannot undo this | Replaces |
| Finds damaged documents: broken lines, garbled OCR, split words and near-duplicates | Reads |
In a generative answer, a sentence that ends with a citation such as [1] is evidence. CrowdSmart checked it against passage 1, or shows the exact words of the passage. A sentence without a citation is the agent's own reasoning. CrowdSmart does not check it against the passages. The API calls passages "chunks".
Set verbose to check or repeat an answer. The response then also has the check result of each sentence (evidence), the number of passages requested and returned (passages), the chunk_id and scores of each citation, and the settings CrowdSmart reports (decision_trace, effective_config, interaction_id).
confidence is a retrieval score from 0 to 1: how well the best passages match the question. A high value shows that the documents match the question. It does not show that the answer is correct.
Jams
A Jam asks Knowledge Agents and people to respond to prompts. Then they review each other's responses. These tools run a Jam of Knowledge Agents on a topic. People take part in the CrowdSmart app.
Tool | What it does | Effect |
| Lists the active Jams that you created, take part in or can join. Your own drafts are not listed | Reads |
| Shows a Jam: its status and prompts. For your own Jams, it also shows the invitees and the agents chosen in the draft | Reads |
| Creates a draft Jam from a plan, with its prompts, agents and invitees. It sends nothing | Adds |
| Launches your draft. The Jam opens, its agents start and the invitees get emails. You cannot undo this | Adds |
| Adds Knowledge Agents to your active Jam | Adds |
| Shows the results so far: participation, mean probabilities and top ideas | Reads |
| Shows each response: its author, probability, text and citations | Reads |
To have Knowledge Agents discuss a topic:
Create three to five agents with
create_knowledge_agent. Give each agent its own perspective inexpertise_headlineandsystem_prompt.Give each agent its own documents with
upload_documentoradd_text_document.Create a Jam with
create_jam. Give one prompt and theagent_idsof the agents.Launch the Jam with
launch_jam.Follow the progress with
get_jam_results. Its counts show what has happened so far, not that the Jam is done: an agent that fails or abstains adds nothing.Read what each agent wrote with
get_jam_responses. Each response has itsauthor_id(the agent's ID) and its citations:[1]in the text is citation 1. Check a cited document withread_document.
In the Jam, each agent responds to the prompt. Then each agent reviews the responses of the other agents. Your agents do not need to be shared to take part in your Jam.
Knowledge Agents answer only the first prompt of a Jam. For more questions, use one Jam for each question.
The tools act as the owner of your API key. Only the creator of a Jam can launch it or add agents to it. The creator is always invited to the Jam and, if invitations are sent, gets the invitation email too.
Knowledge Model Agents
A Knowledge Model Agent (KMA) forecasts the cases of one domain. A domain is a kind of decision: an outcome with its states, and the fields that describe a case. A case is one question in the domain, with an as-of date and a resolution criterion.
A KMA is a Knowledge Agent with one or more perspective models. Each model is a Bayesian belief network that a staged build makes from the KMA's domain sources. You approve each stage. To forecast a case, each model reads the case's evidence through CrowdSmart's pinned reader. The reader runs on CrowdSmart's worker, so the results of a build or a reading come later.
Tool | What it does | Effect |
| Lists every domain, with its outcome, cases and KMAs | Reads |
| Shows a domain: its outcome, case fields, base-rate table, cases and KMAs | Reads |
| Creates a domain that you own | Adds |
| Adds a case to a domain. You cannot remove a case | Adds |
| Sets one profile field of an open case, for example its subject | Replaces |
| Records the outcome of a case. You cannot undo this | Adds |
| Marks a case as not scored, for example when the decision came before the freeze. You cannot undo this | Adds |
| Scores the frozen forecasts of a domain: hits, Brier score and log loss, by KMA | Reads |
| Lists your KMAs, with their domains | Reads |
| Creates a KMA and attaches it to a domain | Adds |
| Makes a Knowledge Agent that you own a KMA, for example to finish a | Replaces |
| Attaches your KMA to a domain. You cannot undo this here | Adds |
| Lists the documents of a KMA, with their extraction review and their tag | Reads |
| Reads the extracted text of a document as the KMA reads it, with its digest | Reads |
| Approves the extracted text of a document, or asks for a correction | Replaces |
| Tags a document as a domain source or as evidence for one case | Replaces |
| Checks the reader, the worker, the domain and the sources before a build | Reads |
| Starts the build of one perspective model | Adds |
| Shows each build: its stage, and the decision it waits for | Queues |
| Makes your decision at a stage of a build: variables, definitions, structure, publish, stop or revise | Replaces |
| Shows the current forecast of a KMA for a case, and the readings behind it | Queues |
| Shows the published models of a KMA: variables, links and priors | Reads |
| Freezes the forecast of a KMA for a case. Only frozen forecasts are scored. You cannot undo this | Adds |
| Shows the adaptive switches of a KMA, and their history | Reads |
| Sets an adaptive switch of a KMA, with the reason | Replaces |
| Lists what a KMA asks people to answer, and the questions so far | Queues |
| Asks a need of members of the domain's cohort | Adds |
| Shows the cohort of a domain: the people invited to answer questions | Reads |
| Invites a person to the cohort of a domain. CrowdSmart sends an email | Adds |
| Removes a person from the cohort of a domain | Replaces |
To build a KMA and forecast a case:
Find or create a domain with
list_kma_domainsorcreate_kma_domain. Add its cases withadd_kma_case. If the domain has asubject_field, the models published on it read each case's evidence a whole document at a time, about the case's subject.Create the KMA on the domain with
create_kma. If it stops partway, it gives the agent's ID: finish withenable_kmaorattach_kma_to_domaininstead of creating another agent.Add its domain sources with
add_text_documentorupload_document. Add the evidence for each case in the same way.Read each extraction with
read_kma_extractionand compare it with the original. This is the text that the KMA reads: headers are removed, the text is cleaned and near-duplicate passages are left out, so it can differ fromread_document. Then approve it withreview_kma_document, giving the digest thatread_kma_extractionreturned.Tag each document with
tag_kma_document:domainfor a domain source, orcasewith its case ID. Give its publication date.Check the KMA with
check_kma_build_preflight. Then start the build withstart_kma_build, with a perspective name and a brief.Follow the build with
get_kma_builds. When it waits for you, decide withdecide_kma_build: choose the variables, check the structure, then publish. Each build lists the actions it accepts now innext_actions. To reject a structure, stop or revise the build. If it waits fortake_published, another perspective was published with a different definition of one of its variables: revise or stop the build.Read the forecast for a case with
get_kma_forecast. When no readings wait, freeze it withfreeze_kma_forecast.When the case resolves, record the outcome with
resolve_kma_case. Then compare the scores withget_kma_scoreboard.
A KMA reads only approved documents. When you approve the last unreviewed document of a KMA, CrowdSmart also starts its older concept and network generation, which makes model calls.
The build decisions belong to the KMA's owner. An agent that uses these tools makes a decision only when the user makes it.
A panel is three or four KMAs on one domain, one for each perspective. The panel forecast is the mean of the frozen forecasts of its members. Compare a panel with the base rate and with its best member. The mean of members that disagree always scores better than the members do on average, so this gain alone does not show skill.
Related MCP server: andish-mcp
Requirements
uv.
uvxgets Python 3.13 and the dependencies when necessary.Git. uv uses it to get the server from GitHub.
A CrowdSmart account and an API key.
Get an API key
Sign in to CrowdSmart and open the User Dashboard.
In the API Key card, generate a key. The key starts with
crc_.Copy the key. CrowdSmart shows it only once.
A new key replaces your old key.
Add the server to your MCP client
Add this entry to the MCP configuration of your client. For Claude Desktop, the file is claude_desktop_config.json.
{
"mcpServers": {
"crowdsmart": {
"command": "uvx",
"args": ["--from", "git+https://github.com/crowdsmart/crowdsmart-research-mcp", "crowdsmart-mcp"],
"env": { "CROWDSMART_API_KEY": "crc_your_key" }
}
}
}To use a local checkout, replace the --from value with the path of the checkout.
Environment variables
Variable | Required | Default | Meaning |
| Yes | Your CrowdSmart API key. The server sends it only to the API URL, as a bearer token in the | |
| No |
| The CrowdSmart API. The server sends your key to this URL, so set it only to a deployment that you trust |
If CROWDSMART_API_KEY is not set, the server stops at startup and writes the reason to stderr.
Scope
The server covers Knowledge Agents, Jams of Knowledge Agents, and the build, forecast and scoring of Knowledge Model Agents. It does not cover other parts of the CrowdSmart platform. These include:
Other agent types and research features
Taking part in a Jam as a person
Jam messages, analytics and exports
Housekeeping, for example archiving a Jam or sending its invitations again
KMA Jams, refits and revisions, Track and runs, and answers to a KMA's questions
Schedules: a domain's jobs that collect evidence, freeze and resolve cases at set times. Your MCP client can do these steps with the tools above
Use the CrowdSmart app for these features.
Development
uv sync
uv run pytest
uv run ruff check src tests
uv run ruff format --check src tests
uv run basedpyrightThe tests use a fake API and an in-process MCP client. Each tool module (knowledge_agents.py, jams.py, kmas.py) has a test file. To list the tools of the real server with the MCP Inspector, run this command once with --protocol-era modern and once with --protocol-era legacy:
npx @modelcontextprotocol/inspector --cli -e CROWDSMART_API_KEY=crc_any \
uvx --from . crowdsmart-mcp --protocol-era modern --method tools/listA tool list makes no API call, so any key value works.
Available Tools
20 toolsadd_agents_to_jamA
Have Knowledge Agents take part in an active Jam you created.
The agents start in the background, as at a launch: every agent responds to the first prompt, then reviews the other responses. Follow them with get_jam_results.
Args: jam_id: ID of an active Jam you created. agent_ids: Knowledge Agent IDs, from list_knowledge_agents.
Inputs: jam_id (required), agent_ids (required). Returns: object
add_text_documentA
Add text to a Knowledge Agent you own, as a new document that keeps its source.
The text is split into passages and can be asked about at once. The source details are stored with every passage, for citations.
Args: agent_id: ID of a Knowledge Agent you own. title: Document title, shown in citations. text: The text to add. source_url: URL of the original source. author: Author of the original source. timestamp: ISO 8601 date when the source was published or created. source_type: Kind of source, for example "web", "note", "transcript" or "email".
Inputs: text (required), title (required), agent_id (required), author, +3 more. Returns: object
ask_knowledge_agentA
Ask a Knowledge Agent a question and get an answer from its documents, with citations.
Generative mode writes an answer. A sentence ending in a citation such as [1] is evidence: it was checked against passage 1, or is shown in the passage's exact words. A sentence without a citation is the agent's own reasoning. Referenced mode returns the cited passages word for word, with no model writing. When the documents do not cover the question, the agent says so.
"confidence" is CrowdSmart's retrieval score, from 0 to 1: how well the best passages match the question. It does not show whether the answer is right. "generation_source" says how the answer was produced (for example "corpus_extractive" or "abstained"). "knowledge_source" is "documents" unless general-knowledge backfill contributed. CrowdSmart records each question in the agent's query history.
Args: agent_id: Knowledge Agent ID, from list_knowledge_agents. question: The question to answer from the agent's documents. mode: "generative" or "referenced". Omit to use the agent's own setting. max_chunks: Number of passages to retrieve (default 5).
Inputs: agent_id (required), question (required), mode, max_chunks. Returns: object
check_corpus_qualityARead-only
Find damaged documents in a Knowledge Agent's corpus, with a recommended fix for each.
Damaged text makes an agent miss topics its documents hold. The check flags text broken one word per line, garbled OCR, words split by stray spaces and near-duplicate documents. It returns a summary and the flagged documents only.
Args: agent_id: Knowledge Agent ID.
Inputs: agent_id (required). Returns: object
create_jamA
Create a draft Jam from a plan. Nothing is sent until you launch it with launch_jam.
Participants respond to each prompt in order, then review each other's responses. A "prediction" prompt (the default) asks for a probability and reasoning. A "reasoning", "qualitative" or "evaluation" prompt asks for reasoning only. Seed reasons are example ideas that participants review from the start. The result has the draft's green_room_url, where you can review and edit it in the app.
A Jam can have Knowledge Agents only: give agent_ids and no invite_emails. Knowledge Agents answer only the first prompt, so give a Jam of agents one prompt, and use one Jam for each question.
Args: title: The Jam's title. prompts: The prompts, in order: text, optional type and seed_reasons. description: What the Jam is about. decision_goal: The decision or learning the Jam serves. expected_output: The result that you want from the Jam. audience: Who takes part. assumptions: Assumptions that participants must know. materials: Reading material: each a name and its text. invite_emails: Email addresses of the people to invite at launch. agent_ids: Knowledge Agents that take part, from create_knowledge_agent or list_knowledge_agents. They start when the Jam launches. public: Whether anyone can find and join the Jam. community_id: The Jam's community, from list_my_communities.
Inputs: title (required), prompts (required), public, audience, +8 more. Returns: object
create_knowledge_agentA
Create a Knowledge Agent that you own. It is private and has no documents yet.
Add documents with upload_document or add_text_document. To let others ask the agent, share it with set_knowledge_agent_visibility. To have several agents discuss a topic, give each one its own perspective (expertise_headline and system_prompt) and its own documents, then put them in a Jam with create_jam. Your agents do not need to be shared to take part in your Jam.
Args: name: The agent's name. expertise_headline: One line on what the agent knows, shown on its card. system_prompt: How the agent describes itself and its focus. It does not need to tell the agent to keep to its documents: it does that already. mode: Default way of answering. "generative" writes answers that cite passages. "referenced" returns the passages word for word. allow_foundation_backfill: Let the agent answer from the model's general knowledge when its documents cannot. Such answers are labeled. community_id: Home community, from list_my_communities. Default: your default community.
Inputs: name (required), expertise_headline (required), mode, community_id, +2 more. Returns: object
delete_documentADestructive
Delete a document from a Knowledge Agent you own. This cannot be undone.
To fix a damaged document, delete it, then upload the original file again.
Args: agent_id: ID of a Knowledge Agent you own. document_id: Document ID, from list_documents.
Inputs: agent_id (required), document_id (required). Returns: object
get_document_statusARead-only
Show whether CrowdSmart has extracted the text of an uploaded document.
Use it when upload_document returned "processing". "status" is "pending" or "processing", then "completed" (with the number of passages) or "failed" (with the error).
Args: agent_id: Knowledge Agent ID. document_id: Document ID, from upload_document.
Inputs: agent_id (required), document_id (required). Returns: object
get_jamARead-only
Show a Jam: its description, status and prompts in order.
Each prompt shows whether it asks for a probability, and the shortest reasoning it accepts. The Jam's creator also sees its invitees and the agents chosen for the draft ("agent_ids").
Args: jam_id: Jam ID, from list_jams or create_jam.
Inputs: jam_id (required). Returns: object
get_jam_responsesARead-only
Read the responses in a Jam: who wrote each one, its probability, text and citations.
Use it to see what each Knowledge Agent said. "author_id" is the agent's ID. A citation such as [1] in the text is citation 1 of the response: read its document with read_document(author_id, document_id). The seed ideas of the Jam's plan have the author_type "seed". "probability" is the author's estimate, for a prediction prompt.
Args: jam_id: Jam ID. prompt_order: Only the responses to this prompt (the first is 0), from get_jam.
Inputs: jam_id (required), prompt_order. Returns: object
get_jam_resultsARead-only
Show a Jam's results: participation, mean probabilities and top ideas.
"funnel" counts what has happened so far, not whether the Jam is done: the participants (people and agents), the participants who responded, the responses, the reviewers and the reviews. An agent that fails or abstains adds nothing. To follow your agents, compare the author_id of each response in get_jam_responses with the agent IDs you gave. "prompts" gives each prompt's number of responses and, for a prediction prompt, the mean probability. "top_ideas" are the five most relevant responses.
Args: jam_id: Jam ID.
Inputs: jam_id (required). Returns: object
launch_jamA
Launch a draft Jam you created. This cannot be undone.
The Jam becomes active, and each invitee gets an invitation email. Its Knowledge Agents start in the background: every agent responds to the first prompt, then reviews the other responses. Follow them with get_jam_results. Check the draft with get_jam first.
Args: jam_id: ID of a draft Jam you created. send_invitations: Send the invitation emails (default true).
Inputs: jam_id (required), send_invitations. Returns: object
list_documentsBRead-only
List the documents in a Knowledge Agent's corpus.
Args: agent_id: Knowledge Agent ID, from list_knowledge_agents.
Inputs: agent_id (required). Returns: object
list_jamsARead-only
List the active Jams you can see: those you created, those you take part in, and public ones.
"relation" is "created", "contributing", "public" (you can join) or "invited_pending". Your own drafts are not listed until you launch them.
Args: community_id: Only the Jams of this community, from list_my_communities.
Inputs: community_id. Returns: object
list_knowledge_agentsARead-only
List the Knowledge Agents you can ask: your own, and those of other people.
A Knowledge Agent answers from its own corpus of documents. Other people's agents are those published to one of your communities, to the whole platform or to the public (and, for an administrator, every agent). "mode" is the agent's default way of answering (see ask_knowledge_agent). "allow_foundation_backfill" means the agent can also answer from the model's general knowledge. Such answers are labeled.
Inputs: no named parameters. Returns: object
list_my_communitiesARead-only
List the communities you belong to, and your default community.
A community ID places a new agent or Jam in that community, or shares a Knowledge Agent with its members.
Inputs: no named parameters. Returns: object
read_documentARead-only
Read the text of a document in a Knowledge Agent's corpus, for example to check a citation.
The text is rebuilt from the stored passages: each passage starts with a "title | Part n of m:" header, and neighboring passages can overlap.
Args: agent_id: Knowledge Agent ID. document_id: Document ID, from list_documents or an answer's citations. max_chars: Maximum number of characters to return (default 20,000).
Inputs: agent_id (required), document_id (required), max_chars. Returns: object
set_knowledge_agent_visibilityADestructive
Choose who can ask a Knowledge Agent you own.
"private": you and platform administrators. "community": the members of one community (give community_id). "platform": anyone signed in who belongs to a community. "public": anyone with the agent's link, without signing in.
Args: agent_id: ID of a Knowledge Agent you own. visibility: "private", "community", "platform" or "public". community_id: The community, for "community", from list_my_communities.
Inputs: agent_id (required), visibility (required), community_id. Returns: object
update_knowledge_agentADestructive
Change the settings of a Knowledge Agent you own. Settings you leave out keep their values.
Args: agent_id: ID of a Knowledge Agent you own. name: New name. expertise_headline: New one-line description. system_prompt: New system prompt. It replaces the current one. mode: New default way of answering: "generative" or "referenced". model: Language model for generative answers.
Inputs: agent_id (required), mode, name, model, +2 more. Returns: object
upload_documentA
Upload a file from this computer to a Knowledge Agent you own, and wait for its text.
Formats: PDF, DOCX, TXT, MD, JSON, CSV, TSV and XLSX. This waits up to 45 seconds while CrowdSmart extracts the text, and returns the status: "completed" (with the number of passages), "failed" (with the error) or "processing" (check later with get_document_status). Upload only files the user chose.
Args: agent_id: ID of a Knowledge Agent you own. path: Path of the file on the computer that runs this server.
Inputs: path (required), agent_id (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Each tool maps to a distinct resource and action. The closest pairs, such as upload_document vs add_text_document and get_jam_results vs get_jam_responses, are clearly separated by names and descriptions.
All tools use consistent snake_case verb_noun naming (list_jams, create_jam, ask_knowledge_agent, set_knowledge_agent_visibility). Compound names remain predictable and readable.
20 tools is somewhat heavy, but the server covers two substantial domains (Jams and Knowledge Agents) and most tools correspond to genuinely distinct operations. There is little obvious filler, though the surface is larger than ideal for quick tool selection.
Core workflows are covered: Jam creation/launch/results and agent/document lifecycle management. However, there is no join_jam despite list_jams advertising public Jams you can join, and no update_jam, delete_jam, or delete_knowledge_agent, leaving lifecycle dead ends.
Maintenance
Related MCP Connectors
Agent-driven search: build, import, tune, search, and score result quality — all over MCP.
Search and manage your team's knowledge from MCP clients.
Make your knowledge agent-ready. One MCP endpoint, 5 connectors, 3 search modes.
Agent communication platform for agent to agent messaging via MCP. Messages, channels, skills.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to connect to hosted Knowz vaults via MCP for knowledge management, supporting operations like search, save, browse, and amend.MIT
- AlicenseNot gradedqualityDmaintenanceEnables MCP-compatible clients to search and query a team knowledge graph, retrieve document context, upload files for indexing, explore entities and connections, and monitor workspace usage and server health.MIT
- FlicenseNot gradedqualityCmaintenanceEnables agents to search, read, publish, and report reuse of problem-solving solutions via MCP.-
- FlicenseNot gradedqualityCmaintenanceEnables AI agents and users to search a unified organizational knowledge warehouse, create and iterate on documents, manage folders and reviews, and curate shareable knowledge packs through any compatible MCP client.-