MCP server

Connect Rowvia tables to an AI agent

Rowvia MCP lets an authorized chatbot or agent work with existing Rowvia tables: list and find tables, read schemas, prompts, and summaries, add rows from URLs, text, or inline files, optionally run processing, check status, search rows, and read selected rows or results. It adds one primary source as one row by default; when reading rows, extended rows can also include related attachments.

Open app Agent Markdown
First automation

Start with a table in the app, then connect MCP

Profile -> Integrations is not a public deep-link route yet. After sign-in, open Profile, go to Integrations, and create a token for a specific table or account.

  1. Create a table in the app and choose a template.
  2. In Profile -> Integrations, create an API token with the needed scopes.
  3. Add a URL or text through an MCP tool to the existing table.
  4. Start processing explicitly and track row status.
  5. Read the results and check cells against the sources.
Setup

Choose the connection type first

ChatGPT web UI

Use the public HTTPS MCP endpoint https://api.rowvia.ai/mcp and Rowvia OAuth. Do not create or copy an API token; after login, ChatGPT receives its own OAuth token for the current Rowvia user.

Local MCP client

Use stdio configuration in Claude Desktop, Cursor, Codex CLI, or a local agent. In this path, the Rowvia API token rvia_... belongs in the client's environment configuration.

Auth

OAuth, MCP token, and REST Bearer token

Do not mix these three modes. The ChatGPT web connector uses Rowvia OAuth without copying a token. Local MCP and the REST API use an rvia_... token, but in different configuration locations.

OAuth, MCP token, and REST Bearer token
Mode When to use Auth Where the token belongs
ChatGPT web connector ChatGPT UI Rowvia OAuth The user does not copy a token
Local MCP Claude Desktop, Cursor, Codex CLI rvia_... API token Local client env config
REST API Own backend or automation Authorization: Bearer rvia_... Server-side config or secret manager

Token safety

  • Never paste an rvia_ token into a shared chat, prompt, or document.
  • Do not put the token in a browser frontend, public JavaScript, or client bundle.
  • Do not send tokens in URLs, query parameters, or imported links.
  • Prefer a table-restricted token for repeated workflows.
  • Start larger processing runs only after confirming the target table and pending-work estimate.
  • Log request_id or processing_run_id, never the full token.
Clients

How authorization differs

ChatGPT uses OAuth

ChatGPT web connects to the public /mcp endpoint and receives an rvoa_... Rowvia OAuth token through login and consent. The user never sees or copies that token and must not enter an rvia_... token into the ChatGPT connector.

Local clients use API tokens

Claude Desktop, Cursor, Codex CLI, and local agents run the Rowvia stdio MCP server through a local command. The rvia_... token belongs in the local client's environment configuration.

ChatGPT

ChatGPT web step by step

1

Sign in to Rowvia

Open Rowvia.ai first and make sure you are signed in to the correct account. The first version uses the user's existing workbook and tables.

2

Enable Developer Mode in ChatGPT

In ChatGPT, open Settings -> Apps & Connectors -> Advanced settings and enable Developer Mode if your plan or workspace allows it. A company or school workspace admin may disable it.

3

Create the connector

In ChatGPT, go to Settings -> Connectors -> Create. Use https://api.rowvia.ai/mcp as the connector URL. ChatGPT discovers Rowvia OAuth from metadata and automatically registers its callback. Local stdio JSON and ROWVIA_API_TOKEN are not used in this flow.

4

Complete Rowvia OAuth

ChatGPT opens Rowvia login and consent. Check the signed-in Rowvia email and allowed actions, then approve the connection. Rowvia issues an rvoa_... OAuth token only for this ChatGPT connector.

5

Use the connector in a new chat

In a new ChatGPT chat, select the Rowvia connector from the tools menu. Start safely: list tables, confirm the target table, then add documents or start processing.

ChatGPT

Values for the ChatGPT form

Name

The user-facing name shown in ChatGPT's tools menu.

Description

Model-facing text. You can copy it exactly as written.

MCP server URL

The only production URL ChatGPT web needs for the Rowvia connector.

Authentication

In this ChatGPT connector flow, do not use API key, bearer token, or ROWVIA_API_TOKEN. The REST API Bearer token is a separate mode.

Local

Local MCP client step by step

1

Create an API token

Open Rowvia Profile -> Integrations and create an rvia_... token. For a normal agent, use the scopes tables:read, rows:read, row:add, and row:process. Add rows:update only for explicit cell corrections.

2

Limit the table when possible

For repeated workflows, prefer a token restricted to one table. The agent then works only with the table the user assigned.

3

Configure the stdio client

Put the command and ROWVIA_API_BASE_URL plus ROWVIA_API_TOKEN environment variables into the local MCP client. The token belongs in env configuration, never in a prompt or shared chat.

Configuration for local MCP clients only

Do not use this stdio JSON for ChatGPT web. It applies to local MCP clients and local agents. The command below is for development from the Rowvia monorepo; for external installation, use the command published in integration settings. Optional cell updates are disabled until ROWVIA_MCP_ENABLE_ROW_UPDATE=true is set.

API base URL

  • Production: https://api.rowvia.ai
{
  "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"
      }
    }
  }
}
Workflow

How the agent should work

1

Find an existing table

Start with rowvia_table_list or rowvia_table_find. If the user did not name an exact table, ask them to confirm the target table.

2

Read schema and prompts

Use rowvia_table_get_schema or the rowvia://tables/{table_id}/schema resource. For automation, use table_id and row_id; row_index is only a display position.

3

Add rows

rowvia_row_add adds URL, text, and small inline source rows to an existing table. Each item creates a new row with a primary source by default; when reading, include_document can return the primary document and documents[] with related attachments. Use rowvia_row_create_source_group for several documents that belong to one logical row; manage existing row attachments with rowvia_row_get_sources, rowvia_row_add_source, and rowvia_row_remove_source. For public or temporarily shared documents, prefer source=url; Rowvia downloads supported documents server-side. HTML URLs are stored as Markdown snapshots.

4

Start processing explicitly

rowvia_row_add has process_after_add defaulting to false. Before larger runs, call rowvia_table_get_pending_work and start processing through rowvia_table_start_processing.

5

Track status and read results

Track the returned processing_run_id with rowvia_processing_get_status. Read results with rowvia_row_get_results or rowvia_row_get using column projection.

MCP

Available tools

Tables and schema

  • rowvia_table_list
  • rowvia_table_find
  • rowvia_table_get_schema
  • rowvia_table_get_summary
  • rowvia_table_get_pending_work

Rows and documents

  • rowvia_row_add
  • rowvia_row_create_source_group
  • rowvia_row_get_sources
  • rowvia_row_add_source
  • rowvia_row_remove_source
  • rowvia_row_list
  • rowvia_row_search
  • rowvia_row_get
  • rowvia_row_get_results

Processing

  • rowvia_table_start_processing
  • rowvia_processing_get_status

Optional correction

  • rowvia_row_update
Context

Resources

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

Chatbot safety rules

  • Never paste the full token into chat or logs.
  • Do not expose rvia_ tokens in public frontend code.
  • Do not log full ChatGPT download_url values, and never send Rowvia tokens to imported URLs.
  • Prefer table-restricted tokens for local automations; for ChatGPT web, follow the OAuth consent.
  • Read rows through bounded windows, not by dumping the whole table.
  • Do not start larger processing runs without explicit confirmation and a pending-work estimate.
  • An empty output cell is processable; a non-empty output cell is skipped according to Rowvia's normal rules.
  • Do not assume a row always has only one file. When reading documents through include_document, treat documents[] as the full source set and document as the legacy primary source.
  • The MCP tools do not delete rows or tables, create tables, change schema, edit prompts, or change billing/admin settings.
  • Optional rowvia_row_update is disabled by default and requires ROWVIA_MCP_ENABLE_ROW_UPDATE=true plus a token with rows:update.

Need a custom integration?

MCP is the path for agents. For backends and scripts, use the REST API with a Bearer token.

Open API consoleIntegrations