Connect an agent

Agent access lets an AI agent you already run work inside your Clivly workspace. The agent connects to Clivly's remote MCP server with a bearer token you issue from Settings → Agents. That token carries its own scopes, so an agent sees only the tools you granted. It inherits no member role.

An agent acts for the organization. It is never a member: it has no login, no seat, and nothing it does is attributed to a person.

The MCP endpoint

The server is https://api.clivly.com/mcp: Clivly's API URL with /mcp on the end. It is one stateless endpoint that accepts POST only, one JSON-RPC message per request (no batches), and keeps no session between requests.

• Clients of every current era work. Clients on MCP revisions 2025-11-25, 2025-06-18 and 2025-03-26 open with the usual initialize handshake — that is most clients today, including Hermes Agent, Claude Code, Cursor and Paperclip. Clients on revision 2026-07-28 skip the handshake and send the version with each request.
• Every request is authenticated with Authorization: Bearer <token> before its body is read.
• tools/list shows only the tools this agent's scopes grant. Calling any other tool gets the same answer as a tool that does not exist.

The limits and refusals page lists what the endpoint returns when it refuses a request.

Turn agent access on

Agent access is off by default for every workspace. While it is off, Settings → Agents says Agent access is off for this workspace and shows a Turn on agent access button. One click turns it on. That creates nothing by itself: no agent can connect until you create one and give it a token.

Once it is on, the Agent access card has Turn off agent access, behind a confirmation. Turning it off refuses every agent's token on its next request and queues no new events. Agents, their history and pending proposals are kept, and work again when you turn access back on.

Owners, admins and developers can turn agent access on or off and manage agents; Settings → Agents is listed for them whether access is on or not. Any member can review an agent's proposals from Ask your CRM.

Create the agent

Choose Connect an agent in Settings → Agents and fill in:

• Name — how the agent appears in the console and the activity log, e.g. Support triage (Hermes).

• Access — a preset, or your own selection of scopes:

  • Read-only — reads contacts, deals, tasks and activity. Changes nothing.
  • Assistant — everything read-only can do, plus adds notes and tasks and drafts emails for review.
  • Operator — every scope, including contact edits and deal moves. Won and Lost still need approval.

  A preset is only a shortcut. The agent is saved with the exact scope pairs it expands to, and those pairs are what the server enforces. See Scopes & tools.

• Token expiry — 30, 90, 180 or 365 days. The default is 90.

• Webhook URL (optional) — where Clivly should send events this agent cares about. See Webhooks.

Copy the token

The token is shown once, when the dialog opens after you create the agent. It looks like ag_ followed by a long random string. Clivly stores only a hash of it, so nobody — including Clivly — can show it to you again.

Put it straight into the agent's configuration or secret store. If you lose it, rotate the token and use the new one.

The same dialog shows a ready-to-paste setup for each client, with your token and the agent's name already filled in. The snippets below are those same snippets with placeholders.

Point your client at Clivly

The examples use an agent named Support triage, which becomes the server key clivly_support_triage. The key is the agent's name, lowercased, with every run of other characters turned into _, prefixed with clivly_.

Hermes Agent

mcp_servers:
  clivly_support_triage:
    url: "https://api.clivly.com/mcp"
    headers:
      Authorization: "Bearer <your agent token>"

Claude Code

claude mcp add --transport http clivly_support_triage https://api.clivly.com/mcp --header "Authorization: Bearer <your agent token>"

Cursor and other clients

Any client that reads the common mcpServers shape takes the same entry.

{
  "mcpServers": {
    "clivly_support_triage": {
      "url": "https://api.clivly.com/mcp",
      "headers": {
        "Authorization": "Bearer <your agent token>"
      }
    }
  }
}

Paperclip

Paperclip is set up through its UI rather than a file:

1. In Paperclip, open Connectors and choose Connect your own MCP server.
2. Paste the server URL: https://api.clivly.com/mcp.
3. When Paperclip asks for a key, paste the agent token. Paperclip sends it as an Authorization header.
4. Set each Clivly action to Allowed, Ask first or Off, then choose which Paperclip agents may use it.

Paperclip's per-action setting is a second gate in front of Clivly's own. It can narrow what the token allows; it cannot widen it.

Manage a connected agent

Each row in Settings → Agents has these actions:

• Rotate token — issues a new token and invalidates the old one in the same write, so there is no moment when both work. The new token is shown once and expires 90 days after the rotation. A revoked agent cannot be rotated.
• Pause / Resume — stops the agent without touching its token. A pause takes effect on the agent's next call, even mid-session.
• Revoke — permanent. The token never works again and the agent's webhook is disabled. A revoked token is never reactivated, because its plaintext may already be in someone else's hands: connect a new agent instead.

Rotate before a token expires to keep the agent working. An expired token is refused like a revoked one.

Pause all agents

Pause all agents at the top of the console is the kill switch. Every agent request in the workspace is refused, and no events are delivered, until someone resumes. It sits on top of each agent's own status, so resuming restores exactly the agents that were running before — a paused agent stays paused.

Review what agents propose

Some changes an agent may not make on its own: a deal moved to Won or Lost, every email draft, and any write while a visitor message is waiting for it (see Limits & security). Those calls return pending_approval to the agent and appear under Ask your CRM for a person to Approve or Reject.

Nothing happens until someone decides.

• Approve makes the change the agent asked for, with the arguments it sent. Every check runs again at that moment — the agent still holds the scope, the record still exists, a synced field is still refused, the stage is still on the deal's pipeline. Only the approval rule itself is skipped.
• If the change no longer applies, approving fails with the reason and the proposal stays pending. Reject it instead.
• Reject discards the proposal. Nothing changes.
• A revoked agent's proposals are never applied. Revoking an agent withdraws trust in what it queued as well. A paused or expired agent's proposals are applied when approved: a person explicitly approved that change, and only revocation withdraws trust in what was queued.

Two people approving the same proposal at once apply it once. A proposal decided by one person cannot be decided again by another.

Approving an email draft

Approving a draft_follow_up_email does not send anything. It turns the proposal into an ordinary pending draft in your draft queue in Ask your CRM, where you edit and send it like any other draft. Sending uses the same path as an assistant draft, so it needs AI turned on for the workspace.

Only a role that can use email drafts may approve an email proposal: owners, admins, developers and members. The support role is refused with Your role cannot review email drafts. Ask an owner, admin, developer or member to approve this one. Any member may still approve every other kind of proposal. No AI credits are charged — Clivly ran no model to write it — and the draft expires after 4 hours like other drafts.