TrackVia MCP
TrackVia MCP connects an AI assistant to your TrackVia account. The assistant works with your real data: apps, tables, views, records, and files. It uses the Model Context Protocol (MCP) over streamable HTTP.
There are two ways to connect. Most people sign in with their own TrackVia login. See Connect your assistant. A service or script instead uses a token from a dedicated account. See Authentication and configuration.
Getting started
What you need
- An active TrackVia account, with whatever role and permissions you normally use. The assistant can only do what your TrackVia login already allows. It gets no extra access.
- One of the supported AI assistants: Claude (claude.ai, Claude Desktop, or Claude Code), ChatGPT (Business, Enterprise, or Edu plan, with Developer Mode on), Perplexity (Pro, Max, or Enterprise plan), Google Gemini Enterprise, Google Antigravity, or Microsoft Copilot Studio.
- The TrackVia MCP server address, below.
- For the service-account path only: a TrackVia Super Admin who can set up a dedicated account and issue it an access token.
Before you connect any assistant, check with your IT or security team about your organization’s policies on AI tools. Some setups, Microsoft Copilot Studio for example, are usually configured once by an IT admin, not by each person.
Connection details
| Field | Value |
|---|---|
| Server address | https://mcp.trackvia.com/mcp |
| Authentication | OAuth 2.0. Sign in with your normal TrackVia username and password. |
| Transport | Streamable HTTP |
Every assistant below connects the same way underneath. Give it the server address above. The first time you use it, you go through a standard browser sign-in screen, hosted by TrackVia. Once you approve the connection, the assistant holds a short-lived access token. TrackVia does not hand out a separate password or a long-lived API key for this path.
Connect your assistant
Claude
claude.ai or Claude Desktop
- Go to Settings → Connectors.
- On a Team or Enterprise plan, an Owner or Primary Owner adds the connector once, under Organization Settings → Connectors. After that, each person connects on their own. On an individual plan (Free, Pro, or Max), any user can add a custom connector.
- Select Add custom connector.
- Enter the server address:
https://mcp.trackvia.com/mcp. - Select Add, then Connect. This sends you to TrackVia’s sign-in page. Log in and approve access.
- Turn the connector on for a conversation, from the tools (”+”) menu.
Claude Code
Register the server from your terminal:
claude mcp add --transport http trackvia https://mcp.trackvia.com/mcpThen run /mcp inside a session, select trackvia, and choose Authenticate. A browser window opens for you to sign in, the same step as the claude.ai flow above.
ChatGPT
- Custom connectors in ChatGPT need a Business, Enterprise, or Edu plan, with Developer Mode on.
- Turn on Developer Mode: Settings → Apps & Connectors → Advanced Settings. An Enterprise or Edu admin can also grant this through Permissions & Roles.
- Go to Settings → Apps & Connectors → Create.
- Enter the server address:
https://mcp.trackvia.com/mcp. - When asked to authenticate, sign in with your TrackVia credentials.
- Select Scan Tools, then Create.
Microsoft Copilot (Copilot Studio)
This integration goes through Copilot Studio’s agent tools. You need Copilot Studio maker access.
- Open the Tools page for your agent. Select Add a tool → New tool → Model Context Protocol.
- Enter a name, a description, and the server address:
https://mcp.trackvia.com/mcp. - Under authentication, choose OAuth 2.0 → Dynamic Discovery first.
- Create the connection, and add it to your agent.
Google Gemini
This needs Gemini Enterprise, Business edition.
- Sign in to Gemini Enterprise, Business edition (business.gemini.google).
- Select Settings & help.
- Select your team. Go to Manage team → Connected Apps.
- Select Add MCP Server and follow the prompts.
Google Antigravity
This works through the Antigravity command-line client and the Antigravity desktop app.
- In your Antigravity chat, ask it to connect: “Connect to the TrackVia MCP server at
https://mcp.trackvia.com/mcpusing OAuth.” - A browser window opens, to TrackVia’s sign-in page.
- Log in with your TrackVia username and password, or your organization’s SSO. Select Authorize.
- Return to Antigravity. It confirms the connection. Your TrackVia tools are ready.
Perplexity
- This needs a Perplexity Pro, Max, or Enterprise plan. Custom connectors are not available on the free tier.
- Select your profile (bottom left), then Settings → Connectors.
- Select + Custom connector, then Remote. Name it, for example “TrackVia”.
- Enter the server address:
https://mcp.trackvia.com/mcp. Under Transport, select Streamable HTTP. - Expand Advanced. Select OAuth 2.0. Enter a Client ID of your choosing.
- Check “I understand custom connectors can introduce risks.” Select Add.
- On an Enterprise plan, an admin can instead add the connector once, under Enterprise settings → Connectors.
Another AI tool
New AI tools reach the market often. Amazon Quick, Cursor, and Codex are three examples this page does not cover yet. If your organization uses an approved AI tool not listed here, contact your TrackVia representative. Some tools connect with no extra work. Others need configuration from TrackVia Engineering first.
Authentication and configuration
Sign in as yourself (OAuth)
This is the path most people use. You sign in through a standard browser screen, with your own TrackVia username and password. TrackVia issues a short-lived access token. The assistant uses that token for each call. TrackVia does not store your password on the assistant’s side, and the server does not keep a long-lived copy of your token.
Use a service account (bearer token)
A script, a CI job, or another automation cannot open a browser to sign in. Give it a pre-issued token instead. A TrackVia Super Admin creates a dedicated service-account user for this and issues its access token. See API Authentication and Access for how to generate one.
The server reads these headers on every call:
| Header | Required | Purpose |
|---|---|---|
Authorization | Yes | Your TrackVia access token, as Bearer <token>. The Bearer prefix is optional. |
X-TrackVia-Host | No | Send a call to a different TrackVia host than your default. |
X-TrackVia-Account-Id | No | Target one account when your token can reach more than one, such as a sandbox. |
One account at a time
A connection reaches one TrackVia account at a time. To work with a different account, disconnect and reconnect (or reauthenticate), rather than trying to hold two accounts open at once.
Tools reference
| Family | Tool | Description |
|---|---|---|
| Bootstrap | whoAmI | Returns the session’s cached AccountContext: {userId, email, defaultAccountId, accounts: […]}. |
| Bootstrap | serverCapabilities | Returns {name, version, tools: [{name, family, since, status, replacedBy?}]} — the authoritative list of what this server exposes, each tool’s family, and how stable it is. |
| Bootstrap | listToolsSummary | Progressive disclosure of the tool surface: returns one page of minimal tool records — {name, title, family, status, summary} — plus an opaque nextCursor when more pages remain. |
| Bootstrap | getToolSchema | Returns the full definition for a single tool — {name, title, description, family, status, since, inputSchema} — where inputSchema is the exact JSON Schema the server advertises for that tool on tools/list. |
| Apps | getApps | Returns every app visible to the caller. |
| Tables | listTables | Lists every table in the given app. |
| Tables | createTable | Creates a new table in the app. |
| Fields | addField | Appends a field to a table. |
| Fields | updateField | Locates a field by id or name and merges updates into it (shallow merge). |
| Views | getViews | Walks every app + every table in the account and returns view summaries. |
| Views | getViewByName | Walks every view in the account and returns the ones with an exact-matching name. |
| Views | getViewRecords | Returns records from a view with offset pagination. |
| Views | createView | Creates a new view on the table. |
| Views | updateView | Applies a partial update to a view (rename, edit filters, replace column projection). |
| Records | getRecord | Returns a single record from a view via the platform’s RecordController. |
| Records | addRecord | Creates a record in a view. |
| Records | addRecords | Creates multiple records in a view in one request. |
| Records | updateRecord | Updates a single record. |
| Files | getRecordFile | Downloads a file (or image) from a record field. |
| Files | uploadRecordFile | Uploads (or replaces) a file in a document or image record field. |
| Forms | getForm | Fetches a single form’s definition. |
| Forms | listForms | Lists every form defined on the given table. |
| Forms | createForm | Creates a new form on the table. |
| Forms | updateForm | Applies a partial update to a form (rename, edit layout, replace projection). |
| Users | getUsers | Returns the account users as normalized {id, email, firstName, lastName, timeZone, status, groups, customFields} entries in {users, count}. |
| Users | addUser | Creates a new account user. |
| Users | findUsersByEmail | Pages the account user list once, then builds a lookup map. |
| Roles | getRole | Fetches a single role by ID, including its full roleRules, resources, forms, and views tree. |
| Roles | listRoles | Lists every role defined on the given app. |
| Roles | createRole | Creates a new role in the account. |
| Roles | updateRole | PUT on /roles/{roleId}. |
| Dashboards | listDashboards | Lists dashboards in the account. |
| Dashboards | createDashboard | Creates a new dashboard in the account. |
| Relationships | createRelationship | Creates a MANY_TO_ONE relationship between two tables and verifies it actually persisted on BOTH sides. |
| Inspect | describeView | Returns the field metadata (structure) for a view plus the total record count. |
| Inspect | describeRecord | Returns the record plus, for every field, its type, required flag, writability, and (for relationship fields) the linked id. |
| Inspect | describeAccount | Fetches every app, every view, and (by default) a handful of sample field names per view in a single response. |
| Inspect | exportAppSchema | The canonical ‘load the entire schema’ call. |
| Query | queryRecords | Paginates a view’s records, then applies filter / sort / select in the MCP server. |
| Query | searchAllViews | Runs /find?q=<keyword> in parallel across every view (optionally scoped to an app) and returns the top matches per view. |
| Workflows | upsertRecord | Looks up a record by uniqueField=uniqueValue. |
| Workflows | bulkUpdateRecords | Queries the view, evaluates the filter client-side, then PUTs the recordData to each matching record (bounded concurrency, default 4). |
| Workflows | previewBulkUpdate | Takes {viewId, filter, recordData} for a filtered bulk record update but performs no writes. |
| Discovery | buildRecordGraph | Walks the parents of a record and the children that point back to it, in one call. |
| Profile | findDuplicates | Paginates the view, groups records by the value of field (or a composite key from fields[]), and returns only the groups with count ≥ minCount. |
| Ingest | importRecordsFromCsv | Parses csv (or accepts a pre-parsed records array), optionally remaps column names via fieldMapping, casts values against the view’s structure, then either batch-creates or upserts on uniqueField. |
| Ingest | previewImport | Same parse + cast + lint pipeline as importRecordsFromCsv but without writing. |
| Aggregation | groupBy | Paginates the view (up to 10k records), optionally applies a filter, groups by field, then computes aggregate (count/sum/avg/min/max) over valueField. |
| Aggregation | trendRecords | Groups records into day/week/month/quarter/year buckets based on dateField, applies the aggregate, and returns [{bucket, value}] sorted ascending. |
| Lifecycle | softDelete | Writes archiveField = archiveValue via updateRecord. |
| Lifecycle | restoreSoftDeleted | Inverse of softDelete. |
| Resolver | resolveView | Returns {viewId, viewName, appName, isDefault} for the matching view, or {match: null, candidates: [...]} when the name is ambiguous. |
| Resolver | resolveField | Returns the metadata of one field on a view — type, fieldMetaId, required, unique, searchable, and choices (if applicable). |
| Resolver | resolveUser | Scans the account-users list and returns the first match. |
| Scaffolding | scaffoldTable | Creates a table with its fields in a single POST (the platform’s TableCreateRequest accepts an inline fields array — there is no fields sub-resource). |
| Scaffolding | scaffoldApp | Creates an app, scaffolds each requested table (with fields inline), and by default creates at least one dashboard so the app has a landing surface from day one. |
| Cross-resource convenience | grantRoleAccessToView | GETs the role, splices a {id, type:'resultProjection', actions[]} entry into resources.views[] (replacing any prior entry for that viewId), then PUTs the role back. |
| Cross-resource convenience | grantRoleAccessToForm | GETs the role, splices a {id, type:'form', actions[]} entry into resources.forms[], then PUTs the role back. |
| View-authoring helpers | createLineChartView | Creates a chartView of type LineChart. |
| View-authoring helpers | createPieChartView | Creates a chartView of type PieChart. |
| View-authoring helpers | createColumnChartView | Creates a chartView of type ColumnChart (vertical bars). |
| Schema helpers | createManyToMany | Creates a junction table and two MANY_TO_ONE relationships (junction -> tableA, junction -> tableB). |
| Automation helpers | publishDashboardToRole | GETs the dashboard, walks elements[] for embedded view IDs (view / viewShortCut / search / searchBarcode), grants the role read access on each, then grants the role the dashboard. |
Limits
| Action | Limit |
|---|---|
| Query or export records | 5,000 records per call |
| Group, aggregate, or find duplicates | Scans up to 5,000 records by default, up to 10,000 with a higher limit set |
| Import from CSV | 1,000 records per call. Matching against existing records for a uniqueField upsert scans up to 10,000 existing rows. |
| Bulk update | 1,000 records per call. Needs confirm: true. Preview the change first with no write. |
What is destructive
Nothing in this tool set hard-deletes a record. A “delete” instead archives the record (soft delete), which you can reverse. A bulk write needs an explicit confirm: true, and a preview tool lets you check the effect before you commit to it.
Usage examples
Once connected, ask your assistant in plain language. Most of these are one sentence.
Getting oriented
I’m new to this account. Give me a one-shot orientation — apps, views, and a few sample fields per view — so I know what I’m working with.
Tell me which tools this server exposes, when each was introduced, and whether any are marked experimental or deprecated.
Finding things across the account
Search every view in the “Operations” app for the word “urgent” and show me the top hits per view.
Which views anywhere in the account have a field called “Priority”?
Reading a single record
Pull record
7421from the “Orders” view with every field annotated — type, required, writable, and linked ids.
Upsert this lead into the “Leads” view, keying on Email — update if it exists, otherwise create.
Bulk changes with a safety net
Preview what would happen if I set
Status="Archived"on every record in “Old Tickets” last updated before 2025-01-01. Don’t write anything yet.
Now archive every “Inactive” contact in the “Contacts” view. confirm: true.
Imports
Here’s a CSV of new leads. Dry-run the import first, using Email as the unique key, and tell me which rows would create vs. update vs. fail validation.
The dry run looks clean. Now actually run the import and upsert on Email.
Data quality
Find duplicate contacts in the “Contacts” view grouped by email, case-insensitive, with at least 2 matches per cluster.
In the “Projects” view, show me every record that’s missing any required field, annotated with which fields are missing.
Exploring relationships
Build a 3-deep graph around record
7421in “Orders” — every parent, every child, every link.
Query and export
Export every “Active” deal as CSV with just Name, Amount, Stage, and CloseDate.
Page through the “Tickets” view filtered to Status=“Open”, sorted by Priority desc — return up to 5000 records.
Schema
Export the full schema of the “Operations” app so I can see every view, every field, every choice, and every relationship target in one JSON blob.
Describe the “Contacts” view — show me every field’s type, requiredness, writability, and choices.
Aggregation and reporting
In “Orders”, group by Status and show me the count and the sum of Amount per group.
Show me a month-by-month trend of new records created in “Leads” this year — bucket by CreatedAt.
Soft delete and lifecycle
Archive record
8890in “Contacts” by setting Archived=true and ArchivedAt=now. Don’t actually delete.
Restore record
8890in “Contacts”: Archived=false, clear ArchivedAt.
User administration
Add a new user, jane@example.com, to the account.
Look up these emails in the account and return the user ids, plus any that didn’t match.
Security
Runs as you, not as a separate account
Every call the assistant makes uses your own TrackVia identity and role. It can see and change exactly what you can see and change today. Connecting an assistant grants it no extra access, to you or to anyone else using it.
Short-lived, not stored
Sign-in uses a standard OAuth 2.0 flow. TrackVia issues a short-lived access token when you sign in. The server uses that token for your request, then discards it. It does not store your password or a long-lived token.
No separate copy of your data
The MCP server passes each request through to TrackVia’s own API in real time. It keeps no copy of your data on its own.
If you use a service account
- Give the service account only the role and permissions the automation needs. Do not use a superadmin role, and do not use your own personal login.
- Set an expiration date on the access token. Rotate it on a regular schedule.
- Treat the token like a password. Keep it in a secret manager or an environment variable. Never put it in a script, a shared document, or version control.
- If the machine or script holding the token is ever decommissioned or compromised, deactivate the token right away and issue a new one.
Governance and administration
- Turning on access. Claude needs an Owner or Primary Owner to add the connector on a Team or Enterprise plan. ChatGPT needs Developer Mode, on a Business, Enterprise, or Edu plan. Copilot Studio needs maker access, plus your organization’s own connector policy. Perplexity lets an Enterprise admin add the connector once, for the whole organization.
- Attribution. A call made through your own sign-in shows up under your own TrackVia identity, the same as if you had made the change yourself in the TrackVia app. A call made through a service account shows up under that account instead.
- Turning off access. If you have concerns about the MCP, or about how a user is using AI against your account, contact productmanagement@trackvia.com.
- Seeing what the assistant did. Changes show up in TrackVia’s standard record history, the same as any other change. There is no separate MCP activity report today.
Troubleshooting and FAQ
| Symptom | Likely cause |
|---|---|
| No TrackVia tools available | The connection did not load. Restart your assistant fully. |
| 401, missing Authorization header | The header is malformed. It needs Bearer plus a space, then the token. |
| 401 on a connection that worked before | The token expired or was deactivated. Reconnect. |
| ”not in the allowlist” | An extra header is set beyond what you need. |
| Wrong account in the responses | Your token or session belongs to a different account. |
| A write was refused | Your connected identity’s role does not allow it. This is expected behavior. |
| Results look cut off | You hit a per-call limit. Narrow your filter, or aggregate first. |
Feedback
This connection is early. If you hit a bug, find a confusing step, or have an idea that would make this more useful for your team, tell us. Email productmanagement@trackvia.com with what you were trying to do, which assistant you were using, and what happened versus what you expected.