--- title: Notehub MCP description: Notehub MCP is the Model Context Protocol server that acts as the interface to Notehub IQ, letting your AI agent ask questions about your deployed products in plain language. source_url: https://dev.blues.io/tools-and-sdks/generative-ai-tools/notehub-mcp/ canonical_url: https://dev.blues.io/tools-and-sdks/generative-ai-tools/notehub-mcp/ markdown_url: https://dev.blues.io/tools-and-sdks/generative-ai-tools/notehub-mcp.md --- # Notehub MCP Notehub MCP is a hosted [Model Context Protocol](https://modelcontextprotocol.io/docs/getting-started/intro) (MCP) server, and it's the interface to [Notehub IQ](https://dev.blues.io/notehub/notehub-walkthrough.md#notehub-iq), the intelligence layer for Notehub. It turns the plain-language questions you ask your AI agent into queries against the Notehub data you already collect, runs them, and reasons over the results. You use the Notehub MCP through **your own AI agent**: the MCP-capable client you already run (e.g. Claude Desktop/Web, Claude Code, Codex, VS Code Copilot, Cursor, and others). Because the Blues storage service behind it is first-party, there is no separate data warehouse to feed. You decide which Notefile data to include and then query it conversationally. The Notehub MCP generates and runs the SQL for you and returns a response. > **Note:** > > It is not possible for any action taken by the Notehub MCP to add, update, or delete any event data stored in Notehub. ## Installation Notehub MCP is a hosted HTTP MCP server available at: ```bash https://mcp.notehub.io/mcp ``` To install Notehub MCP, ask your AI agent to add a new HTTP MCP server using the URL above. For example: > Add a new HTTP MCP server named Notehub MCP using `https://mcp.notehub.io/mcp`. The URL is intended for MCP client configuration and will not open as a webpage in your browser. If your AI agent cannot complete the setup automatically, choose your tool or MCP client below and follow its installation instructions: - [Claude Desktop or Web](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) (recommended) - [Claude Code](https://code.claude.com/docs/en/mcp#installing-mcp-servers) - [GitHub Copilot (VS Code)](https://code.visualstudio.com/docs/agent-customization/mcp-servers) - [Codex](https://learn.chatgpt.com/docs/extend/mcp) - [Cursor](https://cursor.com/docs/mcp#installing-mcp-servers) > **Tip:** > > You can install Notehub MCP by searching for “Notehub” in Claude’s **Connectors** directory. > > ![Notehub MCP listing in Claude](https://dev.blues.io/images/tools-and-sdks/gen-ai/notehub-connector.png?v=3aa793d8) Because the Notehub MCP works with your own product data, connecting requires you to authenticate with your Notehub account. The first time your client connects, it opens a browser window to sign in to Notehub and authorize access; your client then reuses that authorization on subsequent requests. > **Tip:** > > You can validate the installation of the Notehub MCP by simply asking your AI agent: *"Is the Notehub MCP installed and available?"*. Once the Notehub MCP is installed and authorized, you're ready to take your first steps to onboard one or more of your Notehub projects. Note that all interactions with the MCP are conversational and your AI agent will use the MCP to call the [available tools](#mcp-tool-list) on your behalf. ## First Steps Working through your chosen AI agent, we recommend taking these steps for each Notehub project you want to use with the Notehub MCP. > **Warning:** > > In order to onboard a Notehub project, you must be both an "Owner" of the project and also hold a role of "Project Creator", "Billing Manager", or "Admin" in the Organization settings of the project you wish to onboard. > > **This is only for the onboarding step**, as once a project is onboarded, any associated user can query the project. 1. **Choose and onboard a Notehub project** from the projects you own. For example: > List which Notehub projects I have access to. ...and then... > I'd like to onboard \[my project] for use with Notehub MCP. Onboarding automatically creates a **repository** for the project, the container in the storage service where your datasets live. 2. **Create one or more datasets** that will mirror your Notefiles' JSON events with queryable database tables. For example: > Create datasets for my sensor.qo, alert.qo, and command.qo Notefiles. > **Note:** > > **Don't forget your System Notefiles.** Questions about device metadata (signal strength, data usage, session behavior, voltage, location, and so on) can only be answered if a dataset exists for the [System Notefile](https://dev.blues.io/api-reference/system-notefiles.md) that carries it, like `_session.qo`, `_health.qo`, or `_track.qo`. Datasets are only created for the Notefiles you ask for, so if you want to ask these kinds of questions, include those Notefiles too: > > > Also create datasets for my `_session.qo` and `_health.qo` Notefiles. 3. When your datasets are ready (which can take minutes to hours depending on how much data you have), it's now time to **ask questions!** The MCP inspects the schema and runs read-only queries against your stored data to provide answers. For example: > Are any of my devices showing anomalous temperature readings over the past 24 hours? 4. As time goes on, newly added data in Notehub gets **automatically and immediately synced** with your datasets. See below for examples on how to make the most out of Notehub MCP. ### Organizing with Repositories Your datasets live inside a **repository**, a container in the Blues storage service that is scoped to one or more fleets. When you onboard a project, Notehub IQ automatically creates a repository for it, so for many deployments a single repository is all you ever need. However, because a repository can be scoped to specific fleets, you can create additional repositories against the same Notehub project, each covering a different set of fleets. For example, in a project that spans multiple regions, you might keep one repository for your `west-region` fleet and another for `east-region`, so each can be queried independently. Just ask your AI agent: > Create a repository scoped to my `west-region` fleet, and another for my `east-region` fleet. ## Example Usage Every Notehub project is different, but here are some examples of questions you can ask the Notehub MCP of your datasets: - **Cold-chain compliance auditing**: "Did any shipment breach 8°C for more than 15 continuous minutes last week, and which devices?" - **True offline detection vs. store-and-forward**: "Which devices are actually down versus just syncing on an expected periodic basis?" - **Asset-tracking dwell and geofence analysis**: "Which devices left the warehouse (given lat/lon), how long did they sit at each stop, and did any go dark mid-route?" - **Predictive-maintenance drift-hunting**: "Show me devices whose vibration readings or current draw drifted up more than 20% week-over-week." - **Cellular data-cost attribution**: "Which devices are burning the most cellular data, and is it payload size or sync frequency driving it?" - **Satellite/cellular failover and coverage mapping**: "For my Starnote devices, how often are they falling back to satellite, where geographically, and what's the cost delta?" - **Battery and power-health forecasting**: "Rank my solar/battery remote units by how close they are to brown-out." - **Firmware and config-drift auditing**: "Which devices are on stale firmware or have env vars that diverge from the fleet standard?" - **Environmental threshold reporting**: "Generate last month's exceedance report for any air- or water-quality site that crossed a regulatory limit, with timestamps." > **Note:** > > Several of the examples above (data usage, connectivity, power, and location) draw on device metadata rather than your application's own Notefiles. That metadata lives in [System Notefiles](https://dev.blues.io/api-reference/system-notefiles.md), so you need datasets for the likes of `_session.qo`, `_health.qo`, and `_track.qo` before your AI agent can answer those questions. ### Beyond One-Off Questions The Notehub MCP is most useful as one of several tools your AI agent can reach. As Notehub IQ is the read-only source of truth for what is happening across your deployment, you can pair it with the other connectors your agent already has access to (e.g. Slack, a ticketing system, email, and/or other APIs). This way your AI agent can act on an answer instead of just reporting it. You also don't have to be the one doing the asking. If your AI agent can run scheduled tasks or routines, point it at a query on a schedule and let it react to what it finds. > **Tip:** > > For example, schedule a routine to run each morning that asks the Notehub MCP whether any device has crossed a threshold, moved outside its expected area, or gone quiet in the last 24 hours. If everything looks normal, it stays silent. However, if something is off, it can post a summary to Slack and open a ticket with the impacted device IDs. ## MCP Tool List The Notehub MCP exposes the following tools to your AI agent. Most clients invoke these automatically based on your prompt, so you do not necessarily need to have a deep understanding of what each tool does. The tools fall into three distinct groups: - [Discovery Tools](#discovery-tools) (read-only lookups) - [Repositories & Datasets Tools](#repositories-and-datasets-tools) (the operations that set up your data storage) - [Query & Analytics Tools](#query-and-analytics-tools) (where your product questions get answered) ### Discovery Tools Explore what Notehub entities are available to onboard and query: projects, fleets, and Notefile schemas. #### list\_onboardable\_projects List the Notehub projects where you hold the owner role. These are the projects eligible for onboarding. *Example prompts:* > Which of my Notehub projects can I onboard to the Notehub MCP? > List the Notehub projects I own. #### list\_project\_fleets List the fleets within a project, so you can scope a repository to specific fleets. *Example prompts:* > What fleets are in my Cold Chain project? > Show the fleets I could scope a repository to. #### list\_project\_notefile\_schemas List the Notefile schemas observed in a project (i.e. the JSON shape of events per Notefile). *Example prompts:* > What Notefiles and fields are my devices reporting in this project? > Show me the schema for `sensors.qo`. > **Note:** > > Database (`.db` and `.dbs`) Notefiles are excluded from this tool. #### list\_repositories List all storage service repositories reachable with your current credentials. *Example prompts:* > What storage service repositories do I have? > List my repositories. ### Repositories & Datasets Tools Create and manage the storage service repositories and datasets that map your Notefile data into queryable tables. A repository is scoped to one or more fleets, and your datasets live inside it. #### create\_storage\_repository Create a repository scoped to one or more projects or fleets. *Example prompts:* > Create a repository for my Cold Chain project. > Set up a repository scoped to the `west-region` fleet. #### delete\_storage\_repository Permanently delete a repository and all of its datasets. *Example prompts:* > Delete my `test` repository and everything in it. > **Note:** > > This does not impact any event data you already have stored in Notehub. #### infer\_dataset Generate a draft dataset from a Notefile schema. Arrays fields are skipped by default, but you may opt-in to using them. *Example prompts:* > Draft a dataset from my `air-quality.qo` Notefile. > Infer the columns for the `tracker.qo` schema. #### create\_repository\_dataset Create a dataset that maps a Notefile's JSON into database columns. *Example prompts:* > Create a dataset in this repository for `sensors.qo`. #### replace\_repository\_dataset Drop and recreate a dataset to change its field set. *Example prompts:* > Add the new `humidity` field to my `sensors` dataset. #### delete\_repository\_dataset Permanently delete a single dataset from a repository. *Example prompts:* > Remove the `debug` dataset from this repository. > **Note:** > > This does not impact any event data you already have stored in Notehub. ### Query & Analytics Tools Inspect and query your stored datasets. This is where your product questions from the [Example Usage](#example-usage) section get answered. #### describe\_schema Return the schema for a repository (e.g. tables, approximate row counts, and columns with their types). *Example prompts:* > What tables and columns are in my Cold Chain repository? #### get\_table\_sample Return a sample of rows from a table. *Example prompts:* > Show me a few rows from the `sensors` table. #### query\_repository Run read-only SQL (e.g. `SELECT`, `WITH`, `EXPLAIN`, `SHOW`, and `DESCRIBE` only) queries against your stored event data. This is the tool that answers your analytical questions. *Example prompts:* > Did any shipment breach 8°C for more than 15 continuous minutes last week, and which devices? > Which devices are actually down versus just syncing on an expected periodic basis?