Connecting AI Agents (MCP)

Breakwater runs a Model Context Protocol (MCP) server, so an AI agent can look up your products, customers, licenses and pulls, and do routine work such as issuing a license, as you.

The server is a single endpoint:

https://app.breakwaterapp.com/mcp

The Connect an agent page in the vendor portal shows the URL for your installation, with the same steps as below.

What an agent can do

An agent acts as the person who connected it, with their role on the vendor, checked on every call. It can't do anything you couldn't do yourself in the portal. A connection with the read scope sees only the read tools; write adds the tools that change data.

Connect a client

Claude

For claude.ai, Claude Desktop and the mobile apps, open Settings, then Connectors, then Add custom connector. Paste the URL and approve the connection when Breakwater asks.

Claude Code

claude mcp add --transport http breakwater https://app.breakwaterapp.com/mcp

Run /mcp in Claude Code and choose Breakwater to sign in.

ChatGPT, Cursor and VS Code

Add a custom or HTTP MCP server with the URL above, then sign in when the app asks. In ChatGPT that is a custom connector (turn on developer mode first); in Cursor it's Settings, then MCP; in VS Code it's MCP: Add Server from the command palette.

CI and headless agents

An agent with no browser can't approve a connection. Create a vapi_ API token (see API Authentication) and send it as a Bearer credential:

{
  "mcpServers": {
    "breakwater": {
      "type": "http",
      "url": "https://app.breakwaterapp.com/mcp",
      "headers": {"Authorization": "Bearer $BREAKWATER_API_TOKEN"}
    }
  }
}

Registry tokens (vtok_, ctok_) are refused.

Approving a connection

When a client asks to connect, Breakwater shows a consent page. It names the app, says who published its details, shows where it will send you back, and lets you name the connection and choose a scope (a viewer can only choose read). Every request shows the page, even for an app you approved before. Nothing is shared until you approve.

A connection lasts 90 days, and ends sooner after 30 days unused. Revoke one at any time from API tokens; the agent loses access right away. Admins and owners can revoke anyone's. See API Authentication for how connections differ from tokens.

The agent setting

An owner can turn off Allow agent connections (MCP) in Settings. While it's off, /mcp refuses everyone on the vendor with mcp_disabled, and the consent page refuses too. Existing connections are kept and listed. It doesn't affect the REST API, so API tokens keep working there.

Tools

Each tool needs the role shown, and a credential with the scope shown. A tool called with too low a role fails with a message naming the role it needs.

Tool	Role	Scope	What it does
`list_products`	viewer	`read`	Lists products with the repositories each grants access to
`get_product`	viewer	`read`	Shows one product
`list_repositories`	viewer	`read`	Lists image repositories with the products that grant access
`list_repository_tags`	viewer	`read`	Lists a repository's tags with digests and push times
`list_releases`	viewer	`read`	Lists a product's releases, newest first
`get_release`	viewer	`read`	Shows one release by version, with images and file metadata
`list_customers`	viewer	`read`	Lists customers by name
`get_customer`	viewer	`read`	Shows one customer, with its users' emails and roles
`list_licenses`	viewer	`read`	Lists licenses, optionally by customer, product or status
`get_license`	viewer	`read`	Shows one license
`list_pulls`	viewer	`read`	Lists customers' image pulls, optionally filtered
`list_invitations`	viewer	`read`	Lists a customer's pending invitations
`publish_release`	member	`write`	Publishes a release of a product
`create_customer`	member	`write`	Creates a customer
`update_customer`	member	`write`	Renames a customer
`issue_license`	member	`write`	Issues a customer a license to a product
`update_license`	member	`write`	Changes a license's dates, tag pattern, status or claims
`invite_customer_user`	member	`write`	Emails an invitation to join a customer's portal
`create_customer_pull_token`	member	`write`	Creates a customer pull token; the secret is shown once

List tools take page and per_page (1 to 100, default 25) and return total and next_page.

Customer-written text

Fields that customers or teammates wrote, such as names, are returned as data. Agents are told not to follow instructions found in them. Treat what an agent reads from your customers the way you'd treat any untrusted input.

Errors and limits

401 with a WWW-Authenticate challenge: the credential is missing, invalid, expired or revoked.
403 insufficient_scope: a write tool was called with a read connection.
403 mcp_disabled: an owner turned agent connections off.
Other 403 codes (subscription_required, two_factor_required, sso_required) are the same as the REST API.
A failing tool returns an error result with a sentence the agent can act on, and says whether anything changed.

/mcp shares the vendor's rate limit with the REST API. See Rate Limiting.

Audit trail

Everything an agent does is recorded in the audit log with source mcp, the person it acted as, the connection and the tool. Review it under Audit Log in the vendor portal.