Agent quickstart

PackageMaze hosts private npm and PyPI Feeds for an Organization. A Feed is one registry address, https://pkg.packagemaze.com/<organization>/<feed>/, 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. Every public page of this site has a Markdown rendition; the index is https://www.packagemaze.com/llms.txt.

Look before you change anything. Any of these means it is, and names the Feed:

• .npmrc: registry=https://pkg.packagemaze.com/<organization>/<feed>/
• pyproject.toml: [[tool.uv.index]] with url = "https://pkg.packagemaze.com/<organization>/<feed>/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.

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 mcp add --scope user --transport http packagemaze https://api.packagemaze.com/mcp

codex mcp add packagemaze --url https://api.packagemaze.com/mcp --oauth-client-id packagemaze-codex
codex mcp login packagemaze

{
  "mcpServers": {
    "packagemaze": {
      "url": "https://api.packagemaze.com/mcp"
    }
  }
}

VS Code, claude.ai, and any streamable-HTTP client are on 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.

Tell the person exactly this, then stop until they come back: sign in with GitHub at 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.

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:

registry=https://pkg.packagemaze.com/<organization>/<feed>/
replace-registry-host=npmjs

[[tool.uv.index]]
name = "packagemaze"
url = "https://pkg.packagemaze.com/<organization>/<feed>/simple/"
publish-url = "https://pkg.packagemaze.com/<organization>/<feed>/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, Set up pip, uv, and Poetry, and Set up CI.

• 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.

• 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.

• 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.