Overview

Connect an AI client to Data Hub over the Model Context Protocol, including OAuth sign-in, the read and write scopes, and per-client setup.

ForDevelopers and integrators

Data Hub exposes a Model Context Protocol (MCP) server at /mcp/v1 so AI clients can query instruments, runs, files, and watcher health. Clients authenticate by sending you through a browser sign-in.

Catalogs for tools, prompts, and resources are generated from the live server schema, so they match what your client discovers when it connects.

Authentication

The MCP server authenticates with OAuth. All you need to provide is the endpoint URL; for example, https://datahub.example.com/mcp/v1.

The first connection opens your browser:

Read the Authorize application screen. It names the client, the host it redirects to, and the access it’s asking for.

Click Allow.

Your client stores the access token it receives and renews it without asking again. Allow grants everything on the screen: there are no per-permission checkboxes, so click Deny if any line looks wrong.

Scopes

MCP uses two scopes rather than the <resource>:<action> scopes that gate REST requests:

read: required to connect at all, and covers every read-only tool, resource, and prompt
write: additionally required by tools that change something, including claiming runs, commenting, requesting uploads, reprocessing, and deleting

Most clients ask for both, because the server advertises both. A client granted only read still connects and still reads; its first mutating tool call fails with a message naming the missing scope.

Each entry in the tools catalog lists the scope its REST equivalent requires, which tells you what data the tool touches. Over MCP, only read and write are enforced.

The client acts as you, with your role. Admin-only actions, such as deleting someone else’s comment, work over MCP only when you are an admin. Claiming runs and sending feedback work because a signed-in person is behind the client, even though API tokens can’t do either.

Connect a client

Examples use https://datahub.example.com; substitute your deployment host.

Claude Code

claude mcp add --transport http --scope user data-hub https://datahub.example.com/mcp/v1

Confirm that the server was added by running claude mcp list. Then, start a session with claude and run /mcp to authenticate.

Claude Desktop

Remote servers go through Settings → Connectors → Add custom connector. The claude_desktop_config.json file handles local servers only. Paste https://datahub.example.com/mcp/v1 as the URL, click Add, then click Connect to sign in. Leave the OAuth client fields under Advanced settings empty, since Data Hub registers clients on demand.

Claude reaches your server from Anthropic’s infrastructure rather than from your own machine, so the deployment has to be reachable from the public internet. A deployment running on localhost can’t be added this way; use Claude Code or Cursor for local work.

Cursor

Add the server to .cursor/mcp.json in your project, or to ~/.cursor/mcp.json for every project:

{
  "mcpServers": {
    "data-hub": {
      "url": "https://datahub.example.com/mcp/v1"
    }
  }
}

Open Settings → Tools & MCP. The server appears with a Needs authentication label; click it to start the browser flow. The tools show up once you approve the grant.

Other clients

Any client that speaks Streamable HTTP and the MCP authorization spec needs one setting, the URL https://datahub.example.com/mcp/v1. For local development, point at http://localhost:3000/mcp/v1 instead.

Clients that speak MCP but not OAuth can bridge through mcp-remote, which runs the browser flow on their behalf.

Questions about Data Hub

The assistant can answer questions about Data Hub itself, such as how to install a watcher or what a run status means. It searches the documentation and the changelog, reads the page that fits, and links it in its answer. Two tools do this, and both need only the read scope:

search_docs returns up to five matching sections, each with a short excerpt and a link
read_doc returns one page, or one section of a page, as Markdown

The answers come from the docs that ship with your deployment, so they match the version you run, including a staging deployment that is ahead of the published site. Clients that let you attach resources by hand can also attach any page as datahub://docs/<page>, for example datahub://docs/manage-tokens.

The assistant reads the guides and the changelog. It doesn’t read the generated API endpoint pages or the tools, prompts, and resources catalogs, because the client already receives the catalog when it connects. When the docs don’t cover a question, the assistant says so and offers to send feedback about the gap.

Interactive run reports

Clients that support MCP Apps, an extension of the Model Context Protocol, show the same interactive run report as the web app when the assistant calls get_run_report. The report includes image carousels, plate maps, and the Aunty plate with its well charts. Clients without MCP Apps support get the same data as text and describe it instead.

Feedback

The assistant can send feedback about Data Hub for you, for example after a tool call fails. It shows you the draft first and sends it only after you agree. Sending feedback needs only the read scope. The assistant can also list the reports you sent and read one in full, by report ID or by Linear issue ID such as ENG-1476. Feedback tools return an error saying feedback isn’t set up until an admin connects Linear.

Problems with one run’s data belong in a run comment instead, which the assistant can also post.

Machine-readable catalog

Fetch the same catalog these pages render from:

curl https://datahub.example.com/mcp/v1/schema.json

It lists every tool, prompt, and resource, with JSON Schema for arguments and each tool's response. The schema document needs no authentication.

On this page