brapi-mcp-server

Brapi Dataframe Query

brapi_dataframe_query

Run SQL across in-memory dataframes. Dataframes auto-populate when find_* tools spill (named df_<uuid>) — the dataframe name appears inline on every find_* response that spilled (result.dataframe.tableName), so the typical flow is find_* → read the name → query here. Use brapi_dataframe_describe to inspect schema and provenance for a known name. SELECT only — writes/DDL/COPY/PRAGMA/ATTACH/file-reads are rejected. Use SQL as the paging idiom: LIMIT/OFFSET to walk results, projection to trim columns, aggregation to summarize. Use registerAs to chain — the result lands as a new dataframe.

Input Schema

TableJSON Schema

Name	Required	Description
`sql`	Yes	SELECT statement against dataframes. Single statement only — writes, DDL, file reads, and exports are rejected. Use brapi_dataframe_describe to discover available dataframes. SQL is the primary paging idiom: use `LIMIT/OFFSET` to walk a large dataframe, projection to trim columns, and aggregation (`COUNT`, `GROUP BY`, `AVG`) to summarize without materializing every row.
`preview`	No	Cap the number of rows returned in this response (1–1000). When omitted, the deployment-wide response cap applies. Lower this with `registerAs` when you only need a sample to verify the query.
`rowLimit`	No	Hard cap on rows materialized into the response, bounded by the deployment-wide response cap. For larger result sets, use `registerAs` to keep the full result queryable instead of raising this.
`registerAs`	No	Persist the result as a new dataframe under this name. The response still returns at most `preview` rows; the full result remains queryable as a new dataframe. Conflicts with an existing dataframe name fail — drop first via brapi_dataframe_drop. Identifier rules: letters, digits, and underscores; must start with a letter or underscore; max 63 characters.

Output Schema

TableJSON Schema

Name	Required	Description
`cap`	No	Row ceiling that bound the response (the smaller of preview and rowLimit).
`rows`	No	Materialized rows, bounded by preview/rowLimit.
`error`	No	Present when the call failed. Absent on success.
`shown`	No	Rows materialized into `rows`.
`notice`	No	Guidance for reaching the rows this response left out.
`columns`	No	Column metadata in projection order — name and SQL type. Use this to write follow-up queries without round-tripping through brapi_dataframe_describe.
`rowCount`	No	Total rows the query produced (may exceed `rows.length` when capped).
`dataframe`	No	Name of the dataframe holding the full result, populated when `registerAs` was supplied. Reference this name in follow-up queries.
`truncated`	No	True when the response carries fewer rows than the query produced.

Schema Changelog

Changes observed during successful MCP inspections.

First observedSep 19, 2026

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations are uninformative (all three hints false), so the description carries the full burden — and it delivers. It discloses that dataframes auto-populate from find_* spills with a `df_<uuid>` naming convention, that non-SELECT statements are rejected, that responses are capped, and that registerAs creates a persistent side effect (the result lands as a new dataframe). No annotation contradiction: readOnlyHint=false is consistent with the registerAs persistence behavior described.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Six sentences but every clause earns its place: purpose, dataframe source and naming, lookup flow, sibling routing, query constraints, and chaining. Core purpose is front-loaded; the rest is dense with no filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema exists (return values need no explanation) and the annotations are uninformative, the description covers the full operational loop: how dataframes are created, how to discover their names, how to inspect them, what queries are legal, how to page, and how to chain results. Nothing an agent needs to invoke this tool correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% with detailed per-parameter explanations (row caps, conflict behavior for registerAs, identifier rules), so the baseline 3 applies. The description adds only marginal reinforcement — the SQL paging idiom and registerAs chaining — that largely restates what the schema already documents.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource: 'Run SQL across in-memory dataframes.' It then distinguishes itself from siblings by explicitly naming brapi_dataframe_describe (use it to inspect schema/provenance) and the find_* tools (they produce the dataframes). An agent can tell this tool apart from its siblings without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

States the canonical flow explicitly: find_* → read the inline `result.dataframe.tableName` → query here. It routes to the alternative (brapi_dataframe_describe) with the condition that selects it ('inspect schema and provenance for a known name'), and tells the agent when NOT to use it ('SELECT only — writes/DDL/COPY/PRAGMA/ATTACH/file-reads are rejected'). Nothing is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All brapi-mcp-server tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.