Openbridge MCP — User Manual

A guide to driving the Openbridge data‑pipeline platform through the Openbridge MCP server. This manual is written for end users who interact with the MCP through an AI assistant (Claude or any MCP‑enabled client), and for developers who want to understand the tool surface underneath.

The Openbridge MCP URL is: https://mcp.openbridge.com/mcp

The Openbridge MCP is designed to be an AI enabled interface to Openbridge. Nearly everything you would otherwise do by clicking through the Openbridge web console — inspecting pipelines, scheduling backfills, diagnosing failed loads, browsing the tables your data lands in, checking connected accounts — you can do here by asking in plain language. The sections below explain what the server can do, how requests flow, and how to use it as your day‑to‑day control surface.

Openbridge runs your data pipelines. A subscription (also called a pipeline) pulls data from a product (a connector such as Amazon SP‑API, Amazon Ads, Shopify, Google Analytics) into your storage (BigQuery, Snowflake, Redshift, S3, and others).

Each product exposes one or more stages — specific reports or payloads — and each stage lands as a table in your warehouse. The platform also tracks healthchecks (did each load succeed?), jobs / history transactions (each scheduled or one‑off run), remote identities (the external accounts a pipeline authenticates with), and rules (the schema/contract for every table).

The MCP server exposes all of that as a set of tools an AI assistant can call on your behalf. You talk to the assistant in natural language; the assistant translates your intent into the right tool calls, reads the results, and reports back.

This instance reports the following at the time of writing (you can always re‑check by asking the assistant to "get Openbridge capabilities"):

The two SQL query tools are part of the platform's overall surface but are not enabled here, so direct SQL‑against‑warehouse requests will not run on this deployment. Everything else — pipelines, jobs, healthchecks, products, tables/rules, identities — is live.

There are two layers. Most users only need the first.

Just describe what you want. You do not need to know tool names, IDs, or schemas. Good requests name the thing and the intent:

"List my active Amazon Ads pipelines." "Why did the Shopify subscription fail last night?" "Backfill the SP‑API orders subscription for the first week of January." "What tables does my SQP pipeline produce, and what columns are in the campaigns table?" "Which of my connected accounts are invalid and need reauthorizing?"

The assistant figures out which tools to call, in what order, and chains them together. When something is ambiguous (which of several pipelines? which date range?), it will ask.

The server runs in Code Mode, which means the assistant doesn't see 26 individual tools. It sees four meta‑tools and composes calls inside a small Python sandbox:

A single execute() block can chain "find product → list tables → get schema" without round‑tripping for each step. As an end user you never write this code yourself — but it's why a single request like "what columns are in my campaigns table?" can resolve in one turn.

The server authenticates as you via a refresh token (or OAuth, depending on deployment) that's already configured for your session. You never paste credentials into requests, and the assistant will never print tokens back to you. If a connected upstream account (a remote identity) has expired, that surfaces as an auth_error and the assistant will tell you which account needs reauthorizing — it cannot silently refresh an external login on your behalf.

Keep these terms straight and every request below makes sense:

The server groups its tools into seven families. Below, each family lists what it's for, the kinds of things you can ask, and the underlying tools (useful if you're a developer or want to be precise).

Tells you what the server can do right now.

Ask "what can the Openbridge MCP do?" or "is SQL querying enabled?" and the assistant calls get_capabilities() to report the live tool list, enabled features, and envelope version.

The server can also publish its own usage skills via list_skills() / read_skill(uri).

Discover what connectors exist and what data they produce. This is your catalog browser.

The contract for any table — what fields it has and how it's shaped.

Your pipeline inventory and lifecycle management. This is the most‑used family.

Schedule data pulls and inspect individual runs. This is how you backfill and re‑run.

Did the data load? This is your monitoring and triage surface.

The external accounts your pipelines authenticate with, plus a couple of Amazon‑Ads service helpers.

A quick map from "what you want" to "what the MCP does." Phrase requests like the left column.

These show the MCP doing, end to end, what you'd otherwise do by hand in the console. You type the request on the left; the assistant runs the tool chain on the right and reports a clean answer.

You: "Quick status — any pipelines erroring in the last 24 hours, and any connected accounts that went invalid?"

Behind the scenes the assistant lists your subscriptions and remote identities, pulls recent healthchecks, groups failures by error_code, and flags identities marked invalid. You get back a short list of what's broken and why — no console tabs, no scrolling.

You: "What tables does my SQP pipeline land, and when did the search‑terms table last load successfully?"

The assistant resolves the subscription, lists its enabled tables (list_product_tables scoped to the subscription), and checks recent healthchecks for that stage to report the last good load. One question, one answer.

You: "Re‑pull the orders and order‑items stages for that pipeline for March 1–7."

The assistant confirms the subscription is active, looks up the exact stage_ids for only those two stages (never a wildcard), reads back the plan — "14 jobs: 2 stages × 7 days against subscription 128853" — and waits for your go‑ahead before creating the jobs. Then it can monitor the resulting healthchecks for you.

You: "Subscription 128853 had a red load yesterday. What happened?"

It scopes healthchecks to that subscription and day, finds the failing row, drills into the transaction with get_history_by_id, and reports the error_code, message, and file path — the exact identifiers Openbridge support needs if you have to escalate.

The pattern in all four: you express intent once, the MCP composes the multi‑step tool sequence, and you stay in a conversation instead of a dashboard. That's what makes it viable as the primary control surface rather than a sidecar.

The MCP is happy to read anything, but it deliberately pauses before changing your production pipelines.

Actions that always get a read‑back and an explicit "yes" first:

Built‑in guardrails worth knowing:

Habits that make requests resolve faster: name the pipeline or product if you know it; give a concrete date range for backfills (ISO dates); and when you mean a specific run, the history_id or subscription_id removes all ambiguity.

Every hard error comes back in a stable v1 envelope, so the assistant can explain failures consistently. The field that matters is error_kind:

You don't need to memorize these — but if the assistant says "that pipeline's Amazon login has expired" or "we're being rate‑limited, retrying in a moment," this is where that comes from.

To confirm any of the above against the live server at any time, ask your assistant to "get Openbridge capabilities" — it returns the current tool list, enabled features, and contract version.