--- title: "Agent quickstart | PackageMaze docs" description: "For a coding agent asked to use PackageMaze in a repository: what PackageMaze is, how to tell whether the repository already uses it, how to connect over MCP, the setup, dependency, and failure tools in order, and the one step only a person can take." canonical: https://www.packagemaze.com/docs/agent-quickstart/ --- > Documentation index: https://www.packagemaze.com/llms.txt # Agent quickstart You are a coding agent, and someone asked you to use PackageMaze in a repository: to set it up, to add or update a dependency through it, or to find out why an install failed. This page is the whole job, in order. A person can follow it too. **MCP endpoint** ``` https://api.packagemaze.com/mcp ``` ## What PackageMaze is PackageMaze hosts private npm and PyPI Feeds for an Organization. A Feed is one registry address, `https://pkg.packagemaze.com///`, that serves the packages the Organization publishes and the public packages its policy allows, so npm, pnpm, pip, uv, Poetry, CI, and you install through one URL. Every version PackageMaze delivers is recorded under the credential that asked for it, yours included. You work against PackageMaze over MCP. The endpoint above is the only one; the live catalog of tools and the scope each needs is at [https://api.packagemaze.com/v1/mcp/tools](https://api.packagemaze.com/v1/mcp/tools). Every public page of this site has a Markdown rendition; the index is [https://www.packagemaze.com/llms.txt](https://www.packagemaze.com/llms.txt). ## Is the repository already on PackageMaze? Look before you change anything. Any of these means it is, and names the Feed: - `.npmrc`: `registry=https://pkg.packagemaze.com///` - `pyproject.toml`: `[[tool.uv.index]] with url = "https://pkg.packagemaze.com///simple/"` - `pip.conf or PIP_INDEX_URL`: `index-url pointing at the Feed's /simple/ URL` - `.github/workflows/*.yml`: `uses: packagemaze/setup-maze` If none is present, the repository installs from public registries, and setting it up is the job below. If the person has no PackageMaze Organization yet, stop there: only a person can create one. ## Connect over MCP Connecting opens a consent screen in the person's browser that scopes you to one Organization and the Feeds they choose. You cannot complete it yourself. Ask, then wait. ### Claude Code ``` claude mcp add --scope user --transport http packagemaze https://api.packagemaze.com/mcp ``` ### Codex ``` codex mcp add packagemaze --url https://api.packagemaze.com/mcp --oauth-client-id packagemaze-codex codex mcp login packagemaze ``` ### Cursor and other clients **.cursor/mcp.json** ``` { "mcpServers": { "packagemaze": { "url": "https://api.packagemaze.com/mcp" } } } ``` VS Code, claude.ai, and any streamable-HTTP client are on [Connect your agent](https://www.packagemaze.com/docs/connect-your-agent/). Once connected, call `list_feeds` to see what you can reach and `get_organization_setup_readiness` for what the Organization still needs. ## When there is no PackageMaze account yet Tell the person exactly this, then stop until they come back: sign in with GitHub at [https://www.packagemaze.com/login](https://www.packagemaze.com/login) and request access. The Organization is created from their GitHub organization, its first Feeds are created for them, and only an Organization Admin can connect you (above) and approve CI access (below). Do not invent a Feed URL, a Token, or an Organization name in the meantime. ## Set up the repository Three tools, in this order, then one install that proves them, before you say the setup is done: - `get_setup_context`: what PackageMaze can see, which Feeds you may use, and the credential names to reference. Call it first. - Inspect the repository yourself: every place packages are installed or published, every CI workflow. Then `plan_repository_setup` with what you found. It returns the file changes to make, as steps; it changes nothing itself. - Apply the steps, then `review_repository_setup`. It checks the result for coverage. When it passes, the setup is configured, not yet verified: run one install through the Feed with the person's Token, confirm the delivery with `get_package_activity`, and only then is the setup done. The committed files carry the Feed URL and never a Token secret: **.npmrc** ``` registry=https://pkg.packagemaze.com/// replace-registry-host=npmjs ``` **pyproject.toml (uv)** ``` [[tool.uv.index]] name = "packagemaze" url = "https://pkg.packagemaze.com///simple/" publish-url = "https://pkg.packagemaze.com///legacy/" default = true authenticate = "always" ``` Credentials come from the environment (`MAZE_TOKEN`) locally and from a short-lived exchange in CI. Only a person creates the local Token, on the Feed's access page in the PackageMaze App; `plan_repository_setup` returns that link, so relay it instead of running an install that will be refused. For GitHub Actions, `plan_repository_setup` names each area's Project and the exact `create_workload_access_rule` call its workflows need; after that call the person confirms the rule with one click. Name a Project by its repository (owner/name, plus a path inside a monorepo); `get_project_ci_onboarding` reads the workflows' readiness the same way. The full recipes are on [Set up npm and pnpm](https://www.packagemaze.com/docs/set-up-npm-and-pnpm/), [Set up pip, uv, and Poetry](https://www.packagemaze.com/docs/set-up-pip-uv-and-poetry/), and [Set up CI](https://www.packagemaze.com/docs/set-up-ci/). ## Add or update a dependency - `preflight_dependencies` before each add or update: it answers whether the Feed serves the version, whether a policy holds it, and which pin to use. - Apply the pin and run the package client as usual. - `report_dependency_changes` afterwards with the parsed lockfile facts and git state. Your report is user-owned evidence; it never rewrites what CI proved. - `get_agent_activity` to see what you checked and installed, by session. > **Note:** A version held by the Minimum Age Policy (24 hours by default) is not an error. Say that it is held and until when, and pin the version the Feed serves meanwhile. ## Find out why an install or CI run failed - `diagnose_failure` with what you saw: ranked causes, each with its fix. - `get_build_report` for one CI run: the token exchange, resolutions, and install attempts PackageMaze recorded. - `get_package_activity`, `search_packages`, and `get_package` for what was delivered, where a package is hosted, and one package in depth. The causes you will meet most, with their fixes, are on [Fix a failing install](https://www.packagemaze.com/docs/fix-a-failing-install/). ## Rules - Never write a Token secret into a committed file. Reference an environment variable or a CI secret name. - PackageMaze is the only index, never an extra one: no `--extra-index-url`, no supplemental Poetry source. - The Feed URL ends with a slash. A generic unauthorized response means the credential, not the Feed; check the Token's Feed access first. - Keep lockfiles. A Feed serves the same package names, so existing lockfiles stay valid. - Say what you could not verify. A partial setup is reported as partial, never as done. > **Watch out:** Do not claim the setup is complete without `review_repository_setup` and one install confirmed by `get_package_activity`, and do not claim a CI rule exists until the person has confirmed it in PackageMaze. Next: [Connect your agent](https://www.packagemaze.com/docs/connect-your-agent/) Related: [Set up your repository](https://www.packagemaze.com/docs/set-up-your-repository/), [Fix a failing install](https://www.packagemaze.com/docs/fix-a-failing-install/), [Cloud agents and sandboxes](https://www.packagemaze.com/docs/cloud-agents-and-sandboxes/)