> ## Documentation Index
> Fetch the complete documentation index at: https://productos.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP tools reference

> Every tool the ProductOS MCP server exposes to connected AI clients — 55 tools across files, shell, sandboxes, databases, deployments, browser automation, mobile publishing, and multi-surface Product orchestration.

The ProductOS MCP server exposes your entire project — not just its context — to any MCP client such as Claude, ChatGPT, Cursor, Windsurf, or VS Code. Beyond reading your PRD, research, and designs, a connected agent gets the full project sandbox: files, a shell, sandbox lifecycle, databases and storage, GitHub sync, deployments, a headless browser, mobile publishing, and multi-surface Product orchestration — **55 tools in total**.

Every tool is project-scoped and permission-gated. A connection carries one or more scopes, and each tool requires at least one:

| Scope           | Grants                                                            |
| --------------- | ----------------------------------------------------------------- |
| `project:read`  | Read project context, files, status, and logs                     |
| `project:write` | Create or modify files, projects, infrastructure, and deployments |
| `project:exec`  | Run a shell, manage packages, and drive a headless browser        |

<Note>
  You choose the scope per project (or org-wide) when you connect. A read-only connection can never write, and a write is refused mid-session if the grant is downgraded or you lose access to the project.
</Note>

## Project and workspace

| Tool                    | Scope | What it does                                                                                                |
| ----------------------- | ----- | ----------------------------------------------------------------------------------------------------------- |
| `get_project_context`   | read  | Project overview: stage, PRD, and design notes from the wiki                                                |
| `get_project_metadata`  | read  | Type and framework, GitHub repo and branch, database and storage provisioning, sandbox id, and access level |
| `list_projects`         | read  | Every project the connection can access, each with its level, and the active one                            |
| `list_organizations`    | read  | Workspaces the connection spans and your role in each                                                       |
| `list_available_repos`  | read  | Context repositories that can be attached to the project                                                    |
| `open_project`          | write | Set the active project and boot its sandbox, returning a live preview URL                                   |
| `create_project`        | write | Create a new project: registry entry, GitHub repo, and template image                                       |
| `clone_project`         | write | Duplicate a project's docs, settings, and stage data into a new project                                     |
| `delete_project`        | write | Delete a project and reap its sandbox and volume                                                            |
| `set_project_framework` | write | Set the project's framework or template                                                                     |
| `add_context_repo`      | write | Attach an external repository as project context                                                            |

## Files and code

All file tools operate on the project's cloud sandbox at `/home/user`. Every mutation auto-commits to GitHub, so changes survive sandbox recreation.

| Tool                     | Scope | What it does                                    |
| ------------------------ | ----- | ----------------------------------------------- |
| `read_file`              | read  | Read a file from the sandbox, as text or base64 |
| `list_files`             | read  | List a directory in the sandbox                 |
| `read_project_structure` | read  | One-shot recursive file tree, pruned            |
| `search_files`           | read  | Regex content search across the project (grep)  |
| `find_files`             | read  | Find files by name or glob                      |
| `write_file`             | write | Create or overwrite a file, text or base64      |
| `edit_file`              | write | Targeted string-replace edits within a file     |
| `move_file`              | write | Rename or move a file or directory              |
| `delete_file`            | write | Delete a file or directory                      |

## Knowledge and memory

| Tool                 | Scope | What it does                                  |
| -------------------- | ----- | --------------------------------------------- |
| `search_memory`      | read  | Semantic search over the project's memory     |
| `list_decisions`     | read  | Logged PRD and design decisions               |
| `get_decision`       | read  | Fetch a single logged decision                |
| `remember_fact`      | write | Persist a durable fact into project memory    |
| `write_wiki_section` | write | Write or update a section of the project wiki |
| `write_prd_section`  | write | Write or update a section of the PRD          |

## Shell and dependencies

| Tool                  | Scope | What it does                                                           |
| --------------------- | ----- | ---------------------------------------------------------------------- |
| `bash`                | exec  | Full shell in the sandbox: pipes, `&&`, globs, git, npm, tsc, and node |
| `manage_dependencies` | exec  | Add, remove, or install npm packages                                   |

## Sandbox lifecycle

| Tool                 | Scope | What it does                                                                |
| -------------------- | ----- | --------------------------------------------------------------------------- |
| `get_sandbox_status` | read  | Instance status, dev-server health, live preview URL, and last-active time  |
| `get_sandbox_urls`   | read  | Preview, dev, and IDE URLs (Expo-aware)                                     |
| `get_sandbox_logs`   | read  | Tail the dev-server logs                                                    |
| `start_sandbox`      | write | Boot or restore the sandbox and return its URLs                             |
| `stop_sandbox`       | exec  | Delete the sandbox instance; GitHub and the persistent volume are preserved |
| `restart_sandbox`    | exec  | Restart the dev server, or hard-recreate the sandbox                        |

## Git and GitHub

| Tool             | Scope        | What it does                                                         |
| ---------------- | ------------ | -------------------------------------------------------------------- |
| `git_sync`       | read / write | Show working-tree status and recent commits, or commit-push and pull |
| `push_to_github` | write        | Push the latest project files to GitHub as a commit                  |

## Databases, storage, and environment

| Tool                 | Scope | What it does                                                                    |
| -------------------- | ----- | ------------------------------------------------------------------------------- |
| `provision_database` | write | Provision a Postgres database (Neon) and wire `DATABASE_URL` and Prisma         |
| `provision_storage`  | write | Provision isolated file storage and write credentials into the sandbox env      |
| `manage_env_vars`    | write | List (keys only), set, or delete environment variables and sync the sandbox env |

## Deployment and diagnostics

| Tool                | Scope | What it does                                            |
| ------------------- | ----- | ------------------------------------------------------- |
| `trigger_deploy`    | write | Kick off a production deployment                        |
| `get_deploy_status` | read  | Latest production deployment status and URL             |
| `get_deploy_logs`   | read  | Build and deploy logs and error detail for a deployment |

## Browser automation

A headless Chromium runs inside the sandbox, so an agent can drive and inspect the app it is building. These tools require `project:exec`.

| Tool                 | Scope | What it does                                                                 |
| -------------------- | ----- | ---------------------------------------------------------------------------- |
| `browser_navigate`   | exec  | Navigate the sandbox's Chromium to a URL                                     |
| `browser_snapshot`   | exec  | Accessibility-tree snapshot with refs to act on                              |
| `browser_read`       | exec  | Read visible text, HTML, an input value, an attribute, the title, or the URL |
| `browser_screenshot` | exec  | Capture the page as an image                                                 |
| `browser_act`        | exec  | Click, double-click, hover, fill, type, select, check, press keys, or scroll |
| `browser_tabs`       | exec  | List, open, switch, or close browser tabs                                    |
| `browser_debug`      | exec  | Read console output, uncaught exceptions, or captured network requests       |

## Mobile publishing

| Tool                 | Scope        | What it does                                                                               |
| -------------------- | ------------ | ------------------------------------------------------------------------------------------ |
| `mobile_publish`     | read / write | The Expo and EAS pipeline: app identity, EAS build, and App Store or Play Store submission |
| `get_eas_build_logs` | read         | Real failure logs for a mobile EAS build (the Run gradlew or Xcode phase)                  |

## Product mode

A Product groups several platform surfaces (web, mobile, website) that share one frozen spec, one database, and one orchestrator agent.

| Tool                  | Scope        | What it does                                                                                                  |
| --------------------- | ------------ | ------------------------------------------------------------------------------------------------------------- |
| `get_product_context` | read         | Orient in a Product: sibling surfaces, whether the shared spec is frozen, and what the orchestrator is doing  |
| `read_shared_context` | read         | Read the frozen shared contract every surface is built against (PRD, flows, components, tokens, schema)       |
| `manage_product`      | write        | Create or steer a Product: provision the shared database and build the web, mobile, and website surfaces      |
| `product_agent`       | read / write | Read and drive the ProductOS orchestrator that plans, freezes the contract, and dispatches per-surface builds |

## Connecting

Connect the ProductOS MCP server to any client over OAuth: paste the endpoint, sign in, and choose which project or organization the connection can reach and at what scope. See the client walkthroughs for [Cursor](/docs/integrations/cursor) and [Claude](/docs/integrations/claude), or the [MCP overview](/docs/integrations/mcp) for how the protocol fits into ProductOS.

<Note>
  Tool availability follows your scope. A `project:read` connection sees only the read tools above; `project:write` adds the write tools; `project:exec` adds the shell and browser tools.
</Note>