Connect an MCP client

The agaro MCP server lets Claude and other compatible clients operate a workspace through Model Context Protocol. The canonical hosted endpoint is:

https://mcp.agaro.ai/

The hosted server calls agaro's authenticated API. It does not connect directly to the database, so normal workspace, module, role, model permission, record scope, and read only checks still apply.

#Requirements

MCP requires all of the following:

• An active Growth or Scale workspace
• The AI Assistant capability
• A $8 monthly MCP seat assigned to the intended actor
• An active Super Admin or Manager actor
• A key created and managed by a workspace Super Admin
• An MCP client that supports streamable HTTP and custom headers

An inactive subscription blocks MCP even if an old seat flag remains on the user.

#Purchase a seat

Open Settings → API and MCP Keys as a Super Admin. If your user lacks a seat, the page displays the current MCP price and purchase action. Activating a seat updates the workspace provider subscription and is prorated by Stripe for the current period.

The key actor must be the seated user. A headless or unbound key is refused for ordinary workspaces.

#Create the key

1. Enter a descriptive key name.
2. Select the seated Super Admin or Manager under Acts as.
3. Choose an expiry.
4. Select Create MCP key.
5. Copy the full secret immediately and store it in your client's secure configuration.

The plaintext is displayed once. The table stores and shows only a prefix plus metadata.

#Copy the generated config

Use the exact Connection config shown on the settings page. It contains the current workspace identifier and hosted endpoint.

The generated structure is:

{
  "mcpServers": {
    "agaro-erp": {
      "type": "streamable-http",
      "url": "https://mcp.agaro.ai/",
      "headers": {
        "Authorization": "Bearer <your-mcp-key>",
        "X-Workspace-Id": "<workspace-id>"
      }
    }
  }
}

Your client may use a different outer configuration file or key name. Preserve the server type, endpoint, bearer format, and workspace header.

#Test safely

Restart or reload the MCP client after saving configuration. Begin with a read request such as listing clients or checking a known record.

Then verify:

1. The result comes from the intended workspace.
2. The key table updates last used time and call count after normal telemetry delay.
3. A record the actor cannot access is also unavailable through MCP.
4. A low risk test write follows the expected model and role permission.

Do not begin with a send, refund, delete, charge, or payroll mutation.

#Authority model

The key acts as the selected user on every API call. Choose a Manager for routine operations when full workspace administration is unnecessary. Choose a Super Admin only when the integration genuinely needs Super Admin actions.

The key cannot be elevated through a request header. It also cannot exceed the privilege of the Super Admin who created it if that creator's live authority is later lower than the bound actor.

MCP is separate from the in app assistant autonomy toggle. External MCP calls do not become safer because the chat composer is set to Action on Accept. Your MCP client is responsible for its own confirmation UX, while agaro enforces the bound actor and action permissions.

#Tools and action coverage

The hosted bridge exposes MCP tools that dispatch supported registered actions. Named tools provide convenient common operations. The underlying authenticated action surface determines the product capability available to the bridge.

Tool names and action coverage can change as the product evolves. Let the MCP client refresh tool discovery instead of hardcoding a static catalog into instructions.

#Rotate a key

Select Rotate on the key row. Rotation issues a new one time secret and invalidates the old one immediately. Update every client using the key before sending another call.

Use rotation when a secret may have been copied into an unsafe location, when personnel change, or as part of normal credential hygiene.

#Revoke a key

Select Revoke and confirm. All clients using that secret stop working immediately. Revocation cannot be reversed.

Revoke keys for retired devices and automations. Do not leave a never expiring key active merely because its call count is low.

#Troubleshooting

#The settings page shows Upgrade plan

MCP seats are available on Growth and Scale. Change the base plan before purchasing a seat.

#The purchase button is disabled

The platform MCP price may not be configured or the workspace subscription may be read only. Restore billing or contact the platform operator.

#Key creation refuses the actor

The actor must be active, approved, in the same workspace, have role Super Admin or Manager, and hold an active MCP seat.

#The client returns unauthorized or forbidden

Confirm the bearer prefix is present, the full key was copied, the workspace identifier is exact, the key is not expired or revoked, and the actor remains active.

#Calls return 429

Reduce request concurrency and wait at least the returned retry interval. MCP tool loops can produce several API calls from one natural language request.

#The client can read but cannot write

Check the actor's role, model permissions, record scope, installed module, paid entitlement, and workspace subscription state. MCP does not bypass any of them.