MCP server

The OrbitNest MCP server implements the Model Context Protocol, so AI assistants such as Claude Code, Claude Desktop and Cursor can manage your OrbitNest projects with typed tools. It runs locally over stdio and calls the OrbitNest API with your admin session. It never connects to your database directly.

Install

The server is published to npm as @orbitneststudio/mcp-server (binary orbitnest-mcp) and requires Node.js 18 or later. Most clients start it with npx, so you do not need to install it first. This page describes version 1.4.0, which isn't on npm yet. Behavior that is new in 1.4.0 is marked "from version 1.4.0".

Claude Code

claude mcp add orbitnest -- npx -y @orbitneststudio/mcp-server
claude mcp list   # orbitnest should show as connected

To point at a different API, add --env ORBITNEST_API_URL=https://api.example.com before the --.

Claude Desktop

Add the server to claude_desktop_config.json. On macOS the file is in ~/Library/Application Support/Claude/, and on Windows it is in %APPDATA%\Claude\.

{
  "mcpServers": {
    "orbitnest": {
      "command": "npx",
      "args": ["-y", "@orbitneststudio/mcp-server"]
    }
  }
}

Restart Claude Desktop. The OrbitNest tools then appear in the tools menu.

Cursor

Add the same mcpServers entry to ~/.cursor/mcp.json to use it in every workspace, or to .cursor/mcp.json in a project.

VS Code and other clients

Any MCP client that can launch a stdio server works. Use the command npx -y @orbitneststudio/mcp-server, or orbitnest-mcp if you installed the package globally with npm install -g @orbitneststudio/mcp-server. For VS Code, add it to .vscode/mcp.json:

{
  "servers": {
    "orbitnest": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@orbitneststudio/mcp-server"]
    }
  }
}

Sign in

You don't need a token or password in the config. Ask your assistant to sign in, and it calls one of these tools:

After you sign in:

• Tokens are saved to ~/.orbitnest/credentials.json (mode 0600) and loaded again the next time the server starts. The CLI uses the same file, so signing in with either tool signs in both.
• The access token is refreshed automatically when it is within 60 seconds of expiry. The server saves each new refresh token as it rotates.
• From version 1.4.0, refreshes are serialized with the CLI and other MCP servers through ~/.orbitnest/credentials.lock. Before refreshing, the server re-reads the credentials file and adopts a token that another process already rotated, instead of reusing the old one (which would revoke the session). Writes are atomic, keep the file at 0600, and merge into the existing file, so the CLI's stored apiUrl is kept.
• orbitnest_admin_signout revokes the session on the server and deletes the credentials file. From version 1.4.0, if the revoke fails (for example, the session already expired), it still clears local credentials and says so.

Choose a project

Most tools act on the active project. Set it at the start of a session:

You:  List my OrbitNest projects and make my-app the active one.
AI:   [calls orbitnest_list_projects]
      [calls orbitnest_set_active_project with projectId "3f6c1a52-…"]

• orbitnest_set_active_project takes the project UUID (the id from orbitnest_list_projects). It loads the project and caches its schema.
• On startup, the server looks for .orbitnest/config.json in its working directory and each parent directory, and selects the project it names. Run orbitnest link from the CLI in your repo to create that file. The server reads the slug from projectSlug, or from slug in files written by older CLI versions.
• From version 1.4.0, orbitnest_set_active_project saves the project only into the .orbitnest/config.json it found at startup, and never creates one in its working directory (for desktop clients that is often / or a system folder). The result's workspaceConfig field gives the path it saved to, or says why nothing was saved. If caching the schema fails, the project is still selected and the result includes a warning.
• DEFAULT_PROJECT_ID preselects a project when no workspace file is found.
• Every project-scoped tool also accepts an explicit projectId (a UUID) that overrides the active project for that call. Storage tools take projectSlug instead.

Configuration

Set environment variables in the env block of your client's MCP config. All of them are optional.

From version 1.4.0, trailing slashes are removed from ORBITNEST_API_URL. The variables MCP_SERVER_VERSION, DEFAULT_ENVIRONMENT and REQUIRE_DESTRUCTIVE_CONFIRMATION were removed and are ignored. The server reports the version from its own package.json.

{
  "mcpServers": {
    "orbitnest": {
      "command": "npx",
      "args": ["-y", "@orbitneststudio/mcp-server"],
      "env": {
        "DEFAULT_PROJECT_ID": "3f6c1a52-8d0e-4c1b-9a43-1e2f5b7c9d10",
        "LOG_LEVEL": "warn"
      }
    }
  }
}

Tools

The server registers 113 tools. In the tables below, the orbitnest_ prefix is left off tool names. Call them by their full name, for example orbitnest_execute_sql.

Account

From version 1.4.0, fullName is required on the sign-up tools (it replaces the optional name), and verificationCode must be 4 digits. Passwords need at least 8 characters with an uppercase letter, a lowercase letter, a digit and one of @$!%*?&.

These tools manage your OrbitNest admin account. There are no dedicated tools for your app's end users. execute_sql can SELECT from the auth_* tables, but writes to them are blocked. Use the Authentication APIs to manage users.

Projects and API keys

Database

Row-level security

Migrations

The migration tools read files from the machine running the MCP server. They use the same file format and migrations registry table as the CLI. From version 1.4.0, the -- migrate:down marker must be the whole line, as in the CLI. See Migrations.

Edge functions and environment variables

Function source uses the handler format described in Edge functions.

Background jobs

See Background jobs.

Storage

See Storage.

Realtime

See Realtime.

Webhooks and SMS

See Webhooks and Authentication.

Email (SMTP)

See Email & SMTP.

Analytics

Most analytics tools accept from and to (ISO 8601) and some accept granularity, platform and appVersion. See Analytics.

Logs

See Logs & observability.

Project Memory

See Project Memory for parameters and the recommended agent workflow.

Workspace and admins

From version 1.4.0, update_admin sends fullName and email to your own admin record. Changing email needs currentPassword and signs out all your sessions, including this one. isActive uses a separate endpoint and needs the workspace admin role.

See Team & roles.

Resources and prompts

Besides tools, the server provides:

• Server instructions that tell the assistant how to use Project Memory: load context once at session start, write decisions, tasks and events as they happen, and call orbitnest_sync_memory at the end.
• The project://context resource: a short JSON summary of the active project (name, one-line description, stack, item counts). It is capped at 4,000 characters because some clients read resources on every request. When you aren't signed in, it returns { "error": "Not signed in…" } instead of failing.
• The orbitnest_load_project prompt: loads the project's full memory into the conversation in one step.

Safety

The server signs in as you, so every tool can do what your account can do. Review tool calls before you approve them, especially in production projects.

SQL checks

Unless ENABLE_SQL_GUARD=false, orbitnest_execute_sql checks each query before sending it:

• Queries that contain INSERT, UPDATE, DELETE, ALTER, DROP, TRUNCATE, GRANT or REVOKE are rejected unless you pass confirmDestructive: true. SELECT and CREATE run without it.
• Queries that look like injection are blocked outright: a stacked destructive statement (for example ; DROP ...), UNION SELECT, a /* ... */ comment, or a line that ends in a bare --.
• Writes that touch an auth_* table are blocked. Read-only SELECTs are allowed.

The row tools (insert_row, update_row, delete_row and the bulk tools) also refuse auth_* tables. The API applies its own validation on top of these checks.

Confirmation flags

These tools refuse to run unless their confirmation flag is true:

Permissions and plans

• Raw SQL and schema changes are limited to the project's creator: execute_sql, create_table, enable_extension, the migration tools, enable_rls, disable_rls, create_policy and delete_policy. Other workspace members get 403 This operation is restricted to the project owner.
• Any workspace member can read the schema (get_schema), table data, RLS status and policies, and use the row tools.
• The storage, background job and realtime tools work on every plan.
• Plan quotas apply. When a workspace is over a quota, uploads, writes that grow the database, function creation and function invocations return 402 with code QUOTA_EXCEEDED. See Plans & billing.

Example session

You:  Create a posts table with id, title, body, author_id and created_at,
      turn on RLS, and let users update only their own posts.

AI:   [orbitnest_create_table  tableName "posts", enableRLS true]
      [orbitnest_create_policy  command "UPDATE",
         using "author_id = auth.uid()"]
      [orbitnest_add_decision  "posts are owner-editable via RLS"]

      Done. posts exists with RLS on, plus an UPDATE policy limited
      to the row's author. I recorded the decision in project memory.

Studio Assistant

Studio also has a built-in assistant that works without installing anything. Open it from the bot icon in the Studio top bar. It runs on the OrbitNest server, not in your MCP client, and has a smaller, fixed set of tools:

• Questions and how-to requests get a written answer. Requests that map to a tool are carried out immediately. Write actions do not ask for confirmation.
• Project-scoped requests use the project you have open, or one you name in the prompt.
• Requests outside the OrbitNest platform are declined.
• Requests are planned by a Google Gemini model on the OrbitNest server and are logged with the tools they ran.
• Default limits per user: 10 requests per minute, 50 per hour and 1,000 per day, with at most 10 tool steps per request.

To write Project Memory or use the full tool set, use the MCP server.

Troubleshooting