Connect an MCP client

Before you authorise

Every MCP request runs as you — same role checks, same org gates, same audit log. The assistant cannot do anything you could not do yourself in the customer area, and every action is attributed to your customer account and visible under /activity. Each connected MCP client is individually revocable from MCP Integrations.

Refresh tokens carry a 90-day rolling TTL — every refresh extends the window — and access tokens are short-lived (one hour). Revocation invalidates the refresh token immediately; the client is bounced to re-authorise on its next call.

Endpoint

All MCP clients connect to the single Streamable-HTTP endpoint at https://mcp.packagento.com/mcp. The endpoint enforces OAuth on every request; no additional API keys are needed.

Claude Code (recommended)

Claude Code is the primary route in use by Packagento developers. Two equivalent paths:

Add from the shell

Run this once from any terminal — Claude Code stores the server in your user-level config and every session picks it up:

claude mcp add --transport http packagento https://mcp.packagento.com/mcp

To scope the server to a single project instead of every session, add --scope project and run the command from that project's root. The server entry lands in .mcp.json beside your code.

Add from inside an existing session

Already in a Claude Code session? Type /mcp at the prompt to open the MCP server manager. Choose Add server, pick HTTP, and enter https://mcp.packagento.com/mcp.

First-run OAuth

The first time Claude Code calls a Packagento tool, your browser opens the consent screen. Sign in to Packagento if you are not already, click "Allow", and the tool call completes. Subsequent calls in the same session, and every future session on the same machine, run without prompting until the refresh token rotates (every 90 days).

Confirm it is live

Type /mcp at any time to see the connection status; or ask the assistant "who am I on Packagento?" — the whoami tool round-trips through OAuth and returns your customer + active org.

Other MCP-compatible clients

Any client supporting Streamable HTTP MCP transport will work. Point it at https://mcp.packagento.com/mcp and complete OAuth in the browser tab the client launches. The exact UI varies — consult your client's own documentation for "add an MCP server" or "add a custom connector".

Managing connected applications

Each MCP client that completes OAuth shows up under MCP Integrations in your customer area. From there you can see when each application last made a tool call and revoke its access individually. Revocation invalidates the refresh token immediately; the client will prompt you to re-authorise on its next call.

Open MCP Integrations →

What the consent screen shows

The consent screen identifies the requesting application by name and shows the redirect URI it will be sent to. If the application requested specific scopes, those appear too; if it did not, the consent screen omits the section and the application gets the default access for the OAuth client it registered as. Approve "Allow" only for applications you trust to act as you on Packagento.

What "Allow" grants:

• Read access to identity, orgs, vendors, packages, projects, licences, orders, invoices, billing addresses, payment-method metadata (no card numbers), and Git integrations — every list_* / get_* / search_* tool.
• Write access bounded by your existing roles: any tool the application calls is checked against your role in the active org. The assistant cannot escalate a viewer to an admin, or buy on an org you do not belong to. Refunds, vendor approval, and other admin-only actions stay off-limits.
• Charges against saved payment methods only when you explicitly ask the assistant to buy. Stripe Connect billing flows through the same off-session charge path as the storefront — no new card numbers are surfaced to the assistant.

Token lifetime: refresh tokens are 90-day rolling (every refresh extends the window). Access tokens last one hour. Both rotate continuously while a client is active; revoking the integration kills the refresh token immediately.

Try it: starter prompts

After the OAuth dance, try one of these. The assistant will pick the right tool for each goal:

• "Who am I on Packagento?" Round-trips through whoami — the fastest sanity check that the OAuth handshake landed.
• "Show me my Packagento dashboard." get_my_dashboard — identity + active org + every org + counts (projects, licences, orders, pending invites) in one call.
• "Set up a new project called staging-site and give me the auth.json." setup_project — creates the project AND mints its first Composer credential pair in one round trip.
• "Buy loki/magento2-components and attach the licence to my staging-site project." purchase_and_install_packages — cart → off-session charge → licence attach → auth.json, all in one call.

Troubleshooting

The browser never opened the consent screen

Some terminals can't launch the system browser. Run /mcp inside Claude Code (or check the client's logs) to find the authorisation URL it tried to open and paste it into a browser manually. The consent flow itself is identical either way.

I keep getting 401s from the assistant

Either the refresh token was revoked from MCP Integrations or it has hit its 90-day TTL without any use to extend it. Either way the fix is the same: re-run the connect command (or trigger any tool from the assistant); the client will bounce you back through the OAuth consent screen and pick up a fresh token pair.

I revoked an integration but it is still working

Refresh-token revocation is immediate, but any access token already issued remains valid until it expires — up to one hour. After that the client cannot mint a new access token and stops cold. To kill access mid-session, also rotate the Composer credentials on any project the assistant might be touching (rotate_credentials).

How do I switch active org from the assistant?

Ask: "Switch to the Acme org". The assistant calls set_active_org; subsequent cart, project, licence, order, and webhook tools all see the new org as active. get_my_dashboard after the switch is the easiest way to confirm.

How do I see what the assistant actually did?

Every MCP tool call lands in the activity log under /activity in your customer area, tagged mcp.tool.invoked with the tool name, the trace ID, and a parameter summary. Use the trace ID to correlate a single conversation across multiple tool calls.

OAuth completed but the assistant says no Packagento tools are available

Most clients cache the tool list on connect. Run /mcp (Claude Code) or your client's equivalent to refresh the connection — once the OAuth handshake is recorded the tool list populates within a session. If the list stays empty after refresh, your client may not yet support Streamable-HTTP transport; consult its docs for the required transport flag.

The tool list looks short — am I missing tools?

Tools are filtered per session by your buyer / vendor role. A pure buyer never sees vendor-only tools (apply_as_vendor, set_package_pricing, etc.); a vendor without buying activity sees the buyer tools too. Apply as a vendor through the storefront or via bootstrap_vendor, and the vendor toolset appears on the next session.