Knack MCP Server vs. Runtime Data API
The MCP Server manages your app's structure and the Runtime Data API reads and writes records. Knowing which does what explains why your AI builder cannot see your data.
What You'll Learn
The Knack MCP Server and the Runtime Data API do different jobs. The MCP Server is how your AI tool builds and manages your app. The Runtime Data API is how your finished app reads and writes records for the person signed in. Most projects use both, and knowing which does what prevents the most common setup mistakes.
The Short Version
| Knack MCP Server | Runtime Data API | |
|---|---|---|
| Handles | Tables, fields, connections, user roles, access rules, and records | Records |
| Used by | Your AI tool, while you build and manage the app | Your app, while people use it |
| Who it acts as | You, through your Knack account | The person signed in to your app |
| Access rules | Not a user of your app, so it isn't limited to one role's records | Knack applies the signed-in user's access rules to every request |
The MCP Server is for you. The Runtime Data API is for your users.
What the MCP Server Does
The MCP Server is the connection your AI tool uses to work on your app. Through it, your AI tool can:
- Read your tables, fields, connections, and user roles
- Create and change tables and fields
- Configure Data Access Control, including turning enforcement on
- Add, update, or delete individual records, and look them up with a read-only query
- Create sample records for testing
It acts as your Knack account, so it reaches the apps you can open in the Builder and no others.
See What the Knack MCP Server Can and Can't Do for the full list and the actions you can't undo.
Why Your App Shouldn't Use the MCP Server for Records
The MCP Server can work with records, but it does so as you, not as the person using your app. That makes it the wrong path for your app's day-to-day data.
Access rules are built around signed-in users. The Runtime Data API returns only what the signed-in person's role is allowed to see. The MCP Server isn't one of your app's users.
Ownership comes out wrong. Records added through the MCP Server are owned by the App Builder system user. Records your users add through the Runtime Data API are owned by them. See Who Owns a Record Created from a Custom Frontend.
Use the MCP Server's record tools for building and admin work, like checking data, fixing a record, or answering a question about your app. Use the Runtime Data API for everything your users do.
What the Runtime Data API Does
The Runtime Data API is what your finished app uses. Every time someone opens a page, your app asks this API for records and shows what comes back.
Requests go one of two ways.
Signed-in users use OAuth. The person signs in through Knack's hosted page and your app receives a token that represents them. Every request made with that token returns only the records their user role is allowed to see. Knack applies access control on the server, before anything is sent.
Public data uses the public API key. For data with no sign-in, requests use a key that is the literal word public. It isn't a secret and it's safe in your app's code. It requires access control to be enabled and the public role to have permissions on the tables involved.
Which API Key to Use, and Which Never to Use
Two different things get called an API key, and confusing them is a real risk.
| What it is | Safe in app code? | |
|---|---|---|
| Public API key | The literal word public | Yes |
| Private REST API key | Full read and write across your whole app | No |
The private key ignores user roles and Data Access Control entirely. Anything holding it can read and change every record in your app.
Never put your private API key in frontend code or paste it into a chatFrontend code is delivered to every visitor's browser, so a key placed there is readable by anyone who looks. If your AI tool suggests using the private key so it can read your records, the answer is no. Use OAuth for signed-in data and the public key for public data.
Why Most Projects Use Both
A typical build uses each in turn.
- Your AI tool connects through the MCP Server and reads your app's structure
- You describe what you want, and it creates or adjusts tables and access rules
- It writes an app that calls the Runtime Data API
- People sign in, and every request they make goes through the Runtime Data API as them
After launch, you can keep using the MCP Server to manage the app. Your users never touch it.
Common Mistakes
Having your app read records through the MCP Server. Your users' access rules won't apply the way you expect, and records won't be owned by the right people. Use the Runtime Data API.
Sharing the private API key with your AI tool. It bypasses every access rule you've configured. Use the MCP Server's record tools for admin work, and OAuth for your app.
Assuming the public key means your data is public. It only reaches what the public role has permission to see. If access control isn't enabled, it returns a 403 instead.
Treating frontend filtering as security. Knack applies access control before sending a response. Filtering in your app changes what people see, not what they can reach. See Checking That Your Access Rules Actually Work.
Next Steps
- What the Knack MCP Server Can and Can't Do: See every MCP action, its limits, and what can't be undone.
- Runtime Data API: Get the record endpoints and sign-in flow in detail.
- Checking That Your Access Rules Actually Work: Test what each role can really reach.
Updated about 13 hours ago