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 manages your app's structure, and the Runtime Data API reads and writes records. Most projects use both. Knowing which one does what explains the question people ask most often, which is why an AI builder can see your tables but not your data.
The short version
| Knack MCP Server | Runtime Data API | |
|---|---|---|
| Handles | Tables, fields, connections, user roles, access control | Records |
| Used by | Your AI builder, while you are building | Your app, while people are using it |
| When it runs | Build time | Every time someone loads a page |
| Who it acts as | You, the Builder account | The person signed in to your app |
The MCP Server shapes the container. The Runtime Data API moves what goes in it.
What the MCP Server does
The MCP Server is the connection your AI builder uses to work with your app's structure. Through it, a builder can:
- Read your tables, fields, connections, and user roles
- Create and change tables and fields
- Configure Data Access Control, including turning enforcement on
- Create sample records for testing
It acts as your Builder account, so it reaches the apps you can open in the Builder and no others.
What the MCP Server cannot do
It cannot read, create, or change individual records. Sample data is the one exception, and that is for testing rather than real use.
This surprises people, and it is deliberate. Records belong to whoever is signed in to your app, and access to them is governed by the rules you set. A build-time connection acting as your Builder account is the wrong thing to be reading customer data with.
Your builder does not need to see your recordsA common worry is that the AI cannot build correctly without reading your data. It does not need to. Your field names, types, and connections tell it everything about the shape of your data. Your app reads the actual records later, as the person signed in.
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. Access control is applied by Knack, 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 is not a secret and it is 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 builder suggests sharing the private key so it can read your records, the answer for a normal build 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 builder 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
The MCP Server's work is finished before your users arrive. The Runtime Data API's work only starts then.
Common mistakes
Expecting the builder to show you your records. It cannot, and it does not need to. Check your data in the Builder.
Sharing the private API key to work around this. It bypasses every access rule you have configured. Use OAuth instead.
Assuming the public key means your data is public. It only reaches what the public role has been given permission to see. If access control is not enabled, it returns a 403 instead.
Thinking access control is applied by your app. Knack applies it before sending a response. Your app receives only what the signed-in user is allowed to see, which is why you should not filter by user in your frontend.
Next steps
- Connecting Claude Code to Knack covers setting up the MCP Server connection.
- Runtime Data API covers the record endpoints in detail.
- Checking That Your Access Rules Actually Work covers testing what each role can really reach.
Updated 2 days ago