get-perms
Fetch permissions for an app by its ID
LABSCO SUMMARY
Schema and permissions round-trip, so an edit and its verification happen in the same conversation.
get-schema and get-perms hand back the current state — and, if you do not have the local files yet, how to produce them — while push-schema and push-perms send the edited versions up. Because query and transact run against the live app, a schema change can be checked with a real query instead of an assurance that it worked.
What it is
A wrapper around the Instant Platform SDK. It works against one of your InstantDB apps by id — reading and pushing schema and permissions, and running queries and transactions against the live data.
What you get
- An app's schema fetched by app id, and local instant.schema.ts changes pushed back up — get-schema, push-schema
- The same round trip for permissions, through instant.perms.ts — get-perms, push-perms
- InstaQL queries run against an app and returned as JSON, including where clauses and nested relations — query
- Transactions in the platform's step format — update, link and unlink — transact
- An orientation tool for a model that has no context on InstantDB yet — learn
Requirements
A personal access token from your Instant dashboard. Instant hosts the server at https://mcp.instantdb.com — /mcp for clients that speak Streamable HTTP, /sse for older ones. To run it yourself instead: npx -y @instantdb/mcp --token <YOUR_TOKEN>, or put the token in INSTANT_ACCESS_TOKEN. Every tool except learn takes an appId.
Setup effort
One command plus a key — npx -y @instantdb/mcp --token <YOUR_TOKEN>, then supply credentials
USE CASES
01
Adding a field to an app's schema
Read the current schema, edit instant.schema.ts locally, then push the change to the app.
02
Tightening the rules on who can read what
Pull the current permissions, change instant.perms.ts, and push it back.
03
Checking what data is really in there
Run an InstaQL query with a where clause and read the JSON that comes back.
04
Fixing a handful of records without writing a script
Send update steps in a transaction, then query the same namespace to confirm the result.
05
Connecting two entities that should have been related
Apply link or unlink steps against the namespaces involved.
06
Getting an agent oriented before it touches an app
Have it read the introduction first, then the app's own schema.
7 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
get-schema
Fetch schema for an app by its ID!
learn
If you don't have any context provided about InstantDB, use this tool to learn about it!
push-perms
Push local permissions changes for an app to the server. Do this after updating your local instant.perms.ts file. If you don't have an instant.perms.ts file yet, use the get-perms tool to learn how to get this file.
push-schema
Push local schema changes for an app to the server. Do this after updating your local 'instant.schema.ts' file. If you don't have an instant.schema.ts file yet, use the get-schema tool to learn how to get this file.
query
Execute an InstaQL query against an app. Returns the query results as JSON.
Example query to fetch all goals and their todos: {"goals": {"todos": {}}}
Example query with a where clause: {"goals": {"$": {"where": {"status": "active"}}, "todos": {}}}
If you're unsure how to write queries, refer to the documentation: https://instantdb.com/docs/instaql
transact
Execute a transaction against an app. Useful for creating, updating, or deleting data.
Steps use the internal transaction format:
- Create/update: ["update", "namespace", "entity-id", {"attr": "value"}]
- Link: ["link", "namespace", "entity-id", {"linkAttr": "target-id"}]
- Unlink: ["unlink", "namespace", "entity-id", {"linkAttr": "target-id"}]
- Delete: ["delete", "namespace", "entity-id"]
Example steps to create a todo: [["update", "todos", "a-uuid", {"title": "Get fit", "done": false}]]
If you're unsure how to make transactions, refer to the documentation: https://instantdb.com/docs/instaml
BEFORE YOU INSTALL
What to know first
Tools you get
7 tools when we connected.
Requires
- An Instant account — the hosted server signs you in with OAuth
- For the local server: npx on PATH and a personal access token from your Instant dashboard, passed as --token (or INSTANT_ACCESS_TOKEN)
CONTEXT COST
Light Standing cost
Rated by the size of the 7 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
Connect your client
Server setup
npx
TERMINAL
npx -y @instantdb/mcp --token <YOUR_TOKEN>Hosted endpoint
ENDPOINT URL
https://mcp.instantdb.com/mcpAdd this hosted endpoint to your MCP client using the credentials listed under Requirements.
MCP Clients
Claude Code
CLAUDE CODE · TERMINAL
claude mcp add instant -s user -t http https://mcp.instantdb.com/mcpThen run claude, open /mcp, select instant and go through the sign-in flow to your Instant account.
Cursor
CURSOR · JSON
{
"mcpServers": {
"instant": {
"url": "https://mcp.instantdb.com/mcp"
}
}
}Add this to ~/.cursor/mcp.json. Cursor sends you through an OAuth sign-in to your Instant account.
Codex
CODEX · TERMINAL
codex mcp add instant --url "https://mcp.instantdb.com/mcp"Codex needs the rmcp_client feature first: add [features] with rmcp_client = true to ~/.codex/config.toml. A browser opens to sign in to Instant.
Gemini CLI
GEMINI CLI · TERMINAL
gemini mcp add --transport http instant https://mcp.instantdb.com/mcpA browser opens to sign in to Instant; run /mcp inside gemini to see it listed.
Windsurf
WINDSURF · JSON
{
"mcpServers": {
"instant": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://mcp.instantdb.com/sse"
]
}
}
}Add this to ~/.codeium/windsurf/mcp_config.json (macOS/Linux; on Windows the docs start the same args with "cmd", "/c").
Zed
ZED · JSON
{
"context_servers": {
"instant": {
"command": {
"path": "npx",
"args": [
"-y",
"mcp-remote",
"https://mcp.instantdb.com/mcp"
],
"env": {}
},
"settings": {}
}
}
}Add this to your Zed settings.
Claude Desktop
CLAUDE DESKTOP · JSON
{
"mcpServers": {
"instant": {
"command": "npx",
"args": [
"-y",
"@instantdb/mcp",
"--token",
"<YOUR_TOKEN>"
]
}
}
}This runs the server locally: <YOUR_TOKEN> is a personal access token from your Instant dashboard. Save ~/Library/Application Support/Claude/claude_desktop_config.json and restart Claude Desktop.
