MCP integration

Bellwork's Model Context Protocol (MCP) server lets an AI assistant such as Claude, ChatGPT, or Cursor search the K-12 catalog, follow districts, read briefs, build research tables, and run outreach in conversation. Its tools call the same authenticated API the dashboard uses, so the assistant sees what your organization's plan, follows, and modules allow.

Endpoint

Add Bellwork as a remote MCP server (Streamable HTTP):

https://bellwork.ai/api/mcp/bellwork/mcp

In Claude Code:

claude mcp add --transport http Bellwork https://bellwork.ai/api/mcp/bellwork/mcp

Settings → Integrations in Bellwork has step-by-step setup for Claude, ChatGPT, Claude Code, and Cursor. The older /api/mcp/school-scout/mcp address is deprecated (sunset December 31, 2026); use the address above for new connections.

Sign-in and consent

MCP clients sign in with OAuth. A request without a token gets 401 pointing at /.well-known/oauth-protected-resource, which names Bellwork's authorization server. Clients that support dynamic client registration, such as Claude, ChatGPT, and Cursor, register and start sign-in on their own.

Before an app gets a token, Bellwork asks you. The consent screen shows:

• the app's name, and the host it will send you back to (the authorization code only goes there, so check it);
• the account and organization you are signed in as, with Not you? to switch accounts;
• what the app will be able to do: search and read Bellwork data; build and update tables in your projects and run research on them; follow districts and schools and request briefs; draft outreach and manage sequences as you, including turning them on to send.

Choose Allow or Deny. If you are signed out, you sign in first and come back to the same question. If you already allowed the app for the same access, you go straight back to it. Only allow apps you trust.

A server-side agent that cannot run OAuth can send an organization API key as the Bearer token instead; see Authentication.

How access works

• Follows. Following a district or school in a project opens its buying signals, news, leadership changes, and board meetings for that project. Where the plan gates a layer, an unfollowed entity returns a teaser with an exact count, { "data": [], "gated": true, "gated_count": 12 }, and following opens it. Pass the project's project_id to reads so an existing follow applies. A plan can cap how many follows a project holds; at the cap, follow_entity returns FOLLOW_LIMIT with the slots in use.
• Modules. The opportunities, signals, and RFP feeds, email templates, and sequences are organization-wide modules. Without one, its tools say so instead of returning data.
• Contact reveals. find_contact_info researches a missing email, phone, or LinkedIn and draws on the organization's monthly reveal allowance. A contact already revealed to your organization stays revealed.

The bellwork://plan-access resource lists the tools each module gates.

Workflows

Find

find filters districts, schools, or contacts by state, metro, size, grades, locale, assessment results, vendors, and more. A list means any of and a number takes a range, so a whole territory or a shortlist of named districts is one call; describe_entity lists every filter an entity takes. content_search finds districts or schools whose own websites mention a phrase; with status: "followed" and a project_id it searches only the project's follows. Search tools return one page of data for the assistant to reason over. To show results to you, the assistant calls show_search_results with the same filters, which draws an interactive table.

Follow and brief

follow_entity opens a district's or school's layers for a project. Following does not start a brief: create_brief requests the seller-specific deep-research brief, which takes several minutes, and get_brief reads it. get_brief answers ready with the dossier, building with the research trail so far, not_requested when none has been asked for, or failed; for the last two, call create_brief. It is safe to repeat: it reuses a ready brief and never duplicates a build in progress. Where the plan requires a follow first, it answers BRIEF_REQUIRES_FOLLOW.

Tables

A table is saved in a project, with districts or schools as rows. Rows come from a live query, a pinned set, or a saved list.

• create_table makes a table with its columns; update_table renames it, changes its filters or sort, and adds (add_columns) or removes columns. These are the only ways to add a column.
• Columns can hold catalog fields, test scores, annual metrics, data from Bellwork's database, or research questions (ai) answered row by row.
• A structured research column declares fields: text, number, boolean, list, date, vendor, a nested group, or a list of records with roll-ups such as a count or a sum. Fields filter and sort by value, and update_column can split a field into a column of its own.
• A contact_resolution column puts a person on each row: it matches Bellwork's contacts by role keywords, researches the web when none fits, and saves who it finds as a contact.
• update_column edits a column in place. run_column fills cells for up to 200 rows per run; rerun: true refreshes cells that already have answers.
• show_table displays the table and updates it live while research runs. get_table_page and get_table_rows read it back for the assistant.

bellwork://guide/tables is the full column reference.

Outreach and sequences

generate_email drafts an email for a contact, optionally following a saved template (list_email_templates, get_email_template). save_outreach_draft keeps an email the assistant wrote, and save_contact_note records what you learned about a person.

create_sequence and save_sequence draw a multi-step email and LinkedIn sequence. add_people_to_sequence enrolls people and writes their messages for review; get_person_messages, edit_person_message, and rewrite_person_message work on one person's messages. Nothing sends until the sequence is turned on.

get_sequence_stats reports how sequences perform: people enrolled, active, finished, and exited; messages sent by channel; and reply, open, and click rates with the counts behind them. Omit sequence_id for every sequence plus organization totals, and bound dates with from and to. Reply rate is per person contacted; open and click rates are per email sent. Apple Mail Privacy Protection inflates opens, so replies are the better measure. The result's definitions explain every number.

Opportunities

get_opportunities reads the organization's opportunities feed, open items by default; verdict selects pursued, dismissed, not_useful, or all. set_opportunity_verdict files an opportunity the way the Opportunities page does, for everyone on that project. A not_useful verdict and its reason tell the prospecting agent what to stop sending. clear_opportunity_verdict puts one back to open, and refresh_opportunity re-checks whether one still holds and whether there is still time to act.

RFPs

search_rfps searches bids and solicitations across the catalog. It covers K-12 sources by default; k12: false widens it to every public buyer. sort: "closing_soon" puts the soonest live deadlines first and leaves out past-due bids. get_rfps reads one district's or school's bids from the same corpus.

Board meetings and news

get_board_ledger lists one district's board meetings, newest first, with agenda items, minutes, and meeting videos. get_entity_events reads a district's or school's news timeline: leadership changes, budgets, grants, procurement, and more, each with its source. Where the plan includes board search, search_board_meetings, get_board_meeting, and get_board_document search and read the full text of board records, transcripts included, across districts.

The interactive table

In clients that support MCP Apps, show_table and show_search_results draw a table that looks and works like the Bellwork workspace grid:

• live rows with their data and research columns, and each research cell's status, updating while research runs;
• sorting, search, filter chips, and paging, all done on the server;
• a cell panel with the answer's sources, evidence, and research trail;
• record peeks for a district, school, or contact: its brief, people, schools, signals, board meetings, and details, with follow and unfollow;
• running a research column or a single cell, and removing a column;
• each district's and school's favicon, and in its peek the district's brand colour, as in the app;
• CSV export and full screen, where the client allows them;
• Ask Claude hand-offs for anything that needs words, such as a new column, a filter, or an email.

Other clients get a compact markdown table instead.

Capabilities

Your client's tool list is authoritative; Bellwork adds tools without changing the endpoint. The server also publishes reference resources, such as bellwork://guide/platform, and prompts, such as prospect_from_scratch, that clients can offer as starting points.

Pagination

Search and read tools return bounded pages so a large catalog or feed does not flood the assistant's context. Ask it to narrow by time, state, entity, or query first, then continue from the returned next_offset (or page_token for board records) only while the response says there are more results.