# Rowvia MCP Agent Guide

Use this document when an AI agent or chatbot needs to operate Rowvia.ai through Rowvia MCP.

Public docs:

- English: https://rowvia.ai/en/docs/mcp
- Czech: https://rowvia.ai/docs/mcp
- German: https://rowvia.ai/de/docs/mcp

## Purpose

Rowvia MCP lets AI agents work with existing Rowvia tables: list and find tables, read schemas, prompts, and summaries, add rows from URLs, text, inline files, or ChatGPT attachments, optionally run processing, check status, search rows, and read selected rows or results.

It is not a full table-management API. By default, the MCP server can add new rows and trigger configured processing, but it cannot overwrite existing cell values. Optional cell-update tools are disabled by default and require `ROWVIA_MCP_ENABLE_ROW_UPDATE=true` plus a token with the `rows:update` scope.

## Local MCP Clients vs ChatGPT

Local clients such as Claude Desktop, Cursor, Codex CLI, and local agents can run a stdio MCP server through a local command. Put `ROWVIA_API_BASE_URL` and `ROWVIA_API_TOKEN` in the MCP client environment.

ChatGPT cannot directly use a local stdio config. It needs a publicly reachable HTTPS MCP endpoint, for example `https://api.rowvia.ai/mcp`. Availability depends on the user's ChatGPT plan/workspace and whether MCP, custom connectors, or developer mode are enabled.

The hosted ChatGPT connector can pass user-attached documents through Apps SDK file params. Use `rowvia_row_add_chatgpt_document` for this path. It advertises `_meta["openai/fileParams"] = ["file"]` and accepts a required top-level `file` object with a temporary `download_url` reference. Supported ChatGPT attachments are PDF, DOCX, TXT, and Markdown. Do not pass ChatGPT attachments through `documents`, `files`, base64, or manually copied URLs.

## Configuration

Production:

```text
ROWVIA_API_BASE_URL=https://api.rowvia.ai
```

The current package command below is for local development from the Rowvia monorepo. For external installation, use the command published in Rowvia integration settings.

```json
{
  "mcpServers": {
    "rowvia": {
      "command": "npx",
      "args": ["--workspace", "@rowvia/mcp", "rowvia-mcp"],
      "env": {
        "ROWVIA_API_BASE_URL": "https://api.rowvia.ai",
        "ROWVIA_API_TOKEN": "rvia_...",
        "ROWVIA_MCP_ENABLE_ROW_UPDATE": "false"
      }
    }
  }
}
```

## Token Scopes

Create the token in Rowvia Profile -> Integrations.

Recommended scopes for normal row-processing workflows:

- `tables:read`: discover tables, schemas, prompts, and summaries.
- `rows:read`: list, search, and read bounded row windows and selected results.
- `row:add`: add URL, text, and inline file rows through `rowvia_row_add`, and ChatGPT-attached documents through `rowvia_row_add_chatgpt_document`.
- `row:process`: estimate pending work, start row processing, and check processing jobs.

Optional correction scope:

- `rows:update`: use only when the agent must make explicit manual cell corrections through `rowvia_row_update`.

Prefer table-limited tokens when the user wants the agent to work with one table.

## Tools

Tables and schema:

- `rowvia_table_list`: lists visible tables without row data. Input: `limit` up to 100.
- `rowvia_table_find`: finds a table by name. Input: `table_name`, optional `require_single`.
- `rowvia_table_get_schema`: returns columns, readonly state, and full output-column prompts. Input: `table_id`.
- `rowvia_table_get_summary`: returns compact table state, row count, status counts, and output-column count. Input: `table_id`.
- `rowvia_table_get_pending_work`: estimates pending processing for all pending rows or selected rows. Input: `table_id`, `mode`, optional `row_ids`.

Rows and documents:

- `rowvia_row_add_chatgpt_document`: adds one PDF, DOCX, TXT, or Markdown document uploaded in ChatGPT from a top-level `file` object; it can optionally start processing immediately with `process_after_add`.
- `rowvia_row_add`: adds up to 100 document rows from `documents`; it can optionally start processing immediately with `process_after_add`. Do not use it for ChatGPT attachments.
- `rowvia_row_list`: returns a bounded row window. Input: `table_id`, `offset`, `limit` up to 100, optional `column_ids`.
- `rowvia_row_search`: searches rows. Input: `table_id`, `query`, optional `statuses`, `row_filters`, `offset`, `limit`, `column_ids`.
- `rowvia_row_get`: reads explicit `row_ids`; it can include document metadata with `include_document` and limit cells with `column_ids`.
- `rowvia_row_get_results`: reads result cells only for explicit `row_ids`, usually after processing.

Processing:

- `rowvia_table_start_processing`: starts processing for `all_pending` or `selected_rows`; `selected_rows` requires `row_ids`.
- `rowvia_processing_get_status`: returns compact processing job status by `processing_run_id`.

Optional correction tool:

- `rowvia_row_update`: manually updates cells in one row. It is registered only with `ROWVIA_MCP_ENABLE_ROW_UPDATE=true` and requires the `rows:update` scope.

## Resources

- `rowvia://tables`
- `rowvia://tables/{table_id}/schema`
- `rowvia://tables/{table_id}/rows?offset=0&limit=20`

## Row Adding

Use `rowvia_row_add` to add one or more new rows to an existing configured Rowvia table. These rows usually represent documents, URLs, or text sources to be processed.

Supported sources:

- `source=url`
- `source=text`
- `source=file` for small inline base64 files

For `source=url`, send a public or temporary HTTPS URL. Rowvia downloads the document server-side without cookies, auth headers, or JavaScript execution. This is the recommended path for larger PDF, DOCX, TXT, and MD files when the model or ChatGPT can provide a URL. HTML URLs are stored as Markdown snapshots.

Minimal URL payload:

```json
{
  "table_id": "sheet_123",
  "process_after_add": false,
  "documents": [
    {
      "client_id": "invoice-1",
      "source": "url",
      "url": "https://example.com/invoice.pdf",
      "doc_type": "auto"
    }
  ]
}
```

Inline files follow the same account upload limits as the Rowvia app. Hosted HTTP MCP also limits the MCP request body to 2 MB, so do not treat `source=file` as the primary path for larger local files. Supported document MIME types are PDF, DOCX, Markdown, and plain text.

Send ChatGPT document attachments through `rowvia_row_add_chatgpt_document`, not through `rowvia_row_add` and not as base64. The `file` field is a real top-level object in the tool schema. It must include an HTTPS `download_url` and `file_id`; `mime_type` and `file_name` should describe the original PDF, DOCX, TXT, or Markdown attachment. Rowvia forwards those two fields as safe metadata hints so the API can preserve the original file type when the temporary download response uses a generic name or MIME type.

ChatGPT attached-file payload:

```json
{
  "table_id": "sheet_123",
  "process_after_add": false,
  "file": {
    "download_url": "https://files.oaiusercontent.com/...",
    "file_id": "file_abc",
    "mime_type": "application/pdf",
    "file_name": "invoice.pdf"
  }
}
```

The result returns `accepted_count`, `rejected_count`, and per-item entries with `client_id`, `row_id`, `file_id`, `document_name`, `doc_type`, `code`, and `message`.

`process_after_add` defaults to `false`. Processing can consume Processing Units, so agents should only run it when the user asked for it or the MCP request explicitly set it.

## Recommended Agent Workflow

1. Use `rowvia_table_list` or `rowvia_table_find` to identify an existing table. Ask the user to confirm if the target is ambiguous.
2. Use `rowvia_table_get_schema` or `rowvia://tables/{table_id}/schema` before adding rows or processing. Output column prompts are full instructions.
3. Use `rowvia_row_add_chatgpt_document` for a supported document attached in ChatGPT, or `rowvia_row_add` with `process_after_add=false` for URL/text/inline document rows.
4. Inspect the per-item add result. A batch may contain both accepted and rejected documents.
5. Before processing, call `rowvia_table_get_pending_work` and show the estimate if the run is broad or could cost credits.
6. Start processing with `rowvia_table_start_processing`.
7. Store the returned `processing_run_id` and check it with `rowvia_processing_get_status`.
8. Read output values with `rowvia_row_get_results` or `rowvia_row_get` using column projection.

Use `table_id` and `row_id` for automation. `row_index` is only for display and may change if the table is sorted, filtered, or re-imported.

## Examples

Add one invoice URL and process it:

1. `rowvia_table_list`
2. `rowvia_row_add` with `process_after_add=false`
3. `rowvia_table_start_processing` for the returned `row_id`
4. `rowvia_processing_get_status`
5. `rowvia_row_get` for the returned `row_id`

Add rows but do not process:

1. `rowvia_table_list`
2. `rowvia_row_add`
3. `rowvia_row_get` for the returned `row_id` values

Add documents attached in ChatGPT:

1. `rowvia_table_find` or `rowvia_table_list`
2. `rowvia_row_add_chatgpt_document` with top-level `file` and `process_after_add=false`
3. Inspect accepted/rejected items
4. Optionally `rowvia_table_start_processing` for the returned `row_id` values

Reprocess selected rows:

1. `rowvia_row_list` or `rowvia_row_search`
2. `rowvia_table_start_processing` with `selected_rows` and `row_ids`
3. `rowvia_processing_get_status`
4. `rowvia_row_get_results`

## Safety Rules

- Never reveal or log the full API token.
- Do not log full ChatGPT `download_url` values; treat them as temporary sensitive URLs.
- Never send Rowvia tokens to imported URLs.
- Prefer table-restricted tokens for automations.
- Do not dump a whole table. Use bounded windows and column projection.
- Do not process large batches without explicit confirmation.
- Prefer `rowvia_table_get_pending_work` before larger processing runs.
- Empty output cell means processable. Non-empty output cell means skipped according to Rowvia's normal rules.
- Rowvia MCP follows the same Rowvia authentication, owner context, quotas, billing, and audit logging as the web app.
- MCP tools do not delete rows or tables, create tables, change schema, edit prompts, or change billing/admin settings.