Skip to main content
Glama
crowdsmart-mcp

crowdsmart-mcp

by crowdsmart

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

list_my_communities

Lists your communities and your default community. A new agent or Jam goes into a community

Reads

list_community_members

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

list_knowledge_agents

Lists your agents and the agents shared with you

Reads

create_knowledge_agent

Creates a private agent with no documents

Adds

update_knowledge_agent

Changes the name, headline, instructions or mode of your agent

Replaces

set_knowledge_agent_visibility

Sets who can ask your agent

Replaces

ask_knowledge_agent

Asks an agent a question. The answer cites the agent's documents and has a confidence score. With verbose, it also shows the evidence checks, passage counts and settings

Adds the question to the agent's query history

list_documents

Lists the documents of an agent

Reads

read_document

Returns the text of a document, for example to check a citation

Reads

upload_document

Uploads a file from this computer to your agent, then waits for its text

Adds

get_document_status

Shows whether the text of an uploaded document is ready, or why it failed

Reads

add_text_document

Adds text with its source (URL, author, date) to your agent

Adds

delete_document

Deletes a document from your agent. You cannot undo this

Replaces

check_corpus_quality

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

list_jams

Lists the active Jams that you created, take part in or can join. Your own drafts are not listed

Reads

get_jam

Shows a Jam: its status and prompts. For your own Jams, it also shows the invitees and the agents chosen in the draft

Reads

create_jam

Creates a draft Jam from a plan, with its prompts, agents and invitees. It sends nothing

Adds

launch_jam

Launches your draft. The Jam opens, its agents start and the invitees get emails. You cannot undo this

Adds

add_agents_to_jam

Adds Knowledge Agents to your active Jam

Adds

get_jam_results

Shows the results so far: participation, mean probabilities and top ideas

Reads

get_jam_responses

Shows each response: its author, probability, text and citations

Reads

To have Knowledge Agents discuss a topic:

  1. Create three to five agents with create_knowledge_agent. Give each agent its own perspective in expertise_headline and system_prompt.

  2. Give each agent its own documents with upload_document or add_text_document.

  3. Create a Jam with create_jam. Give one prompt and the agent_ids of the agents.

  4. Launch the Jam with launch_jam.

  5. 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.

  6. Read what each agent wrote with get_jam_responses. Each response has its author_id (the agent's ID) and its citations: [1] in the text is citation 1. Check a cited document with read_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

list_kma_domains

Lists every domain, with its outcome, cases and KMAs

Reads

get_kma_domain

Shows a domain: its outcome, case fields, base-rate table, cases and KMAs

Reads

create_kma_domain

Creates a domain that you own

Adds

add_kma_case

Adds a case to a domain. You cannot remove a case

Adds

set_kma_case_profile

Sets one profile field of an open case, for example its subject

Replaces

resolve_kma_case

Records the outcome of a case. You cannot undo this

Adds

mark_kma_case_unscored

Marks a case as not scored, for example when the decision came before the freeze. You cannot undo this

Adds

get_kma_scoreboard

Scores the frozen forecasts of a domain: hits, Brier score and log loss, by KMA

Reads

list_kmas

Lists your KMAs, with their domains

Reads

create_kma

Creates a KMA and attaches it to a domain

Adds

enable_kma

Makes a Knowledge Agent that you own a KMA, for example to finish a create_kma that stopped

Replaces

attach_kma_to_domain

Attaches your KMA to a domain. You cannot undo this here

Adds

list_kma_documents

Lists the documents of a KMA, with their extraction review and their tag

Reads

read_kma_extraction

Reads the extracted text of a document as the KMA reads it, with its digest

Reads

review_kma_document

Approves the extracted text of a document, or asks for a correction

Replaces

tag_kma_document

Tags a document as a domain source or as evidence for one case

Replaces

check_kma_build_preflight

Checks the reader, the worker, the domain and the sources before a build

Reads

start_kma_build

Starts the build of one perspective model

Adds

get_kma_builds

Shows each build: its stage, and the decision it waits for

Queues

decide_kma_build

Makes your decision at a stage of a build: variables, definitions, structure, publish, stop or revise

Replaces

get_kma_forecast

Shows the current forecast of a KMA for a case, and the readings behind it

Queues

get_kma_model

Shows the published models of a KMA: variables, links and priors

Reads

freeze_kma_forecast

Freezes the forecast of a KMA for a case. Only frozen forecasts are scored. You cannot undo this

Adds

get_kma_switches

Shows the adaptive switches of a KMA, and their history

Reads

set_kma_switch

Sets an adaptive switch of a KMA, with the reason

Replaces

list_kma_needs

Lists what a KMA asks people to answer, and the questions so far

Queues

ask_kma_need

Asks a need of members of the domain's cohort

Adds

get_kma_cohort

Shows the cohort of a domain: the people invited to answer questions

Reads

invite_to_kma_cohort

Invites a person to the cohort of a domain. CrowdSmart sends an email

Adds

remove_from_kma_cohort

Removes a person from the cohort of a domain

Replaces

To build a KMA and forecast a case:

  1. Find or create a domain with list_kma_domains or create_kma_domain. Add its cases with add_kma_case. If the domain has a subject_field, the models published on it read each case's evidence a whole document at a time, about the case's subject.

  2. Create the KMA on the domain with create_kma. If it stops partway, it gives the agent's ID: finish with enable_kma or attach_kma_to_domain instead of creating another agent.

  3. Add its domain sources with add_text_document or upload_document. Add the evidence for each case in the same way.

  4. Read each extraction with read_kma_extraction and 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 from read_document. Then approve it with review_kma_document, giving the digest that read_kma_extraction returned.

  5. Tag each document with tag_kma_document: domain for a domain source, or case with its case ID. Give its publication date.

  6. Check the KMA with check_kma_build_preflight. Then start the build with start_kma_build, with a perspective name and a brief.

  7. Follow the build with get_kma_builds. When it waits for you, decide with decide_kma_build: choose the variables, check the structure, then publish. Each build lists the actions it accepts now in next_actions. To reject a structure, stop or revise the build. If it waits for take_published, another perspective was published with a different definition of one of its variables: revise or stop the build.

  8. Read the forecast for a case with get_kma_forecast. When no readings wait, freeze it with freeze_kma_forecast.

  9. When the case resolves, record the outcome with resolve_kma_case. Then compare the scores with get_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. uvx gets 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

  1. Sign in to CrowdSmart and open the User Dashboard.

  2. In the API Key card, generate a key. The key starts with crc_.

  3. 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

CROWDSMART_API_KEY

Yes

Your CrowdSmart API key. The server sends it only to the API URL, as a bearer token in the Authorization header

CROWDSMART_API_URL

No

https://csgcip.onrender.com

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 basedpyright

The 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/list

A tool list makes no API call, so any key value works.

Available Tools

20 tools
add_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_qualityA
Read-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_documentA
Destructive

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_statusA
Read-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_jamA
Read-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_responsesA
Read-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_resultsA
Read-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_documentsB
Read-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_jamsA
Read-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_agentsA
Read-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_communitiesA
Read-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_documentA
Read-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_visibilityA
Destructive

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_agentA
Destructive

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

    A3.9/5.0

    Scored across 20 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness3/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to connect to hosted Knowz vaults via MCP for knowledge management, supporting operations like search, save, browse, and amend.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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