Connect an MCP client to Winly

Winly's Model Context Protocol (MCP) server lets a compatible AI client use Winly tools to read CRM data and, when permitted, perform actions such as sending a message or updating a contact.

For example, you can ask a connected client to:

• Find contacts who have not replied recently.

• Summarize response rates or pipeline performance.

• Search conversations for a phrase or objection.

• Review an Inbox queue.

• Send a direct message to an existing contact after you approve the action.

MCP adds another way to work with Winly. It does not replace the Inbox, reports, workflows, or Autopilot.

Before you start

Use the Winly MCP endpoint

Enter this remote MCP server URL in your client:

https://app.sbccrm.com/bld/api/mcp

Choose the authentication method supported by the client.

Prefer OAuth for an interactive client. Use an API key for a trusted client or non-interactive environment that cannot use OAuth.

Connect with OAuth

The exact names of the controls differ between MCP clients, but the connection flow is the same:

1. Open the client's MCP, connector, or integrations settings.

2. Add a remote or custom MCP server.

3. Enter a recognizable name such as Winly.

4. Enter https://app.sbccrm.com/bld/api/mcp as the server URL.

5. Start the connection.

6. In the browser window opened by the client, sign in to the intended Winly account.

7. Review the requested read and write access.

8. Select Authorize.

9. Return to the client and confirm that Winly is connected and its tools are listed.

Only a Winly administrator can approve the OAuth consent screen. If a non-administrator tries to authorize the connection, Winly rejects the request.

Connect with an API key

Create the key

1. Open Settings → MCP.

2. Under MCP API Keys, select Create API Key.

3. Enter a descriptive name that identifies the client or environment.

4. Select Create.

5. Copy the complete key immediately and store it securely.

6. Select Done only after confirming that the key was saved.

The key starts with mcp_ and is displayed only once. If it is lost, revoke it and create another key.

Use one key per client or environment. For example, do not reuse a workstation key for an automated server.

Configure the client

Configure the client to send these values with MCP requests:

A representative configuration looks like this, but the property names can differ between clients:

{
  "mcpServers": {
    "winly": {
      "type": "http",
      "url": "https://app.sbccrm.com/bld/api/mcp",
      "headers": {
        "X-API-Key": "YOUR_MCP_API_KEY"
      }
    }
  }
}

Follow the client's documentation for where to place its MCP configuration. Never commit a real key to source control or include it in a screenshot.

Verify the connection

1. Confirm that the client reports the Winly server as connected.

2. Open the client's available-tool list.

3. Start with a read-only request, such as asking for a lead summary over a short date range.

4. Confirm that the response refers to the intended account.

5. Before testing a write tool, review the proposed contact, message, or setting change and require confirmation in the client.

One client response can call several MCP tools. Review the tool activity shown by the client rather than assuming one question produces only one request.

Understand the available tools

The server currently registers 34 tools. The tools a request can use also depend on the data and product features configured for the account.

Analytics and discovery

Analytics tools that accept a date range limit it to 90 days per request.

Configuration and contact lists

Read the current configuration before asking a client to change it. Send only the fields that should change, then read the configuration again to confirm the result.

Inbox and messaging

Keep these limitations in mind:

• send_dm cannot cold-message a new handle. The contact must already exist in Winly.

• send_dm supports text messages up to 1,000 characters through Instagram.

• Tag tools do not create tags. Create the tag in Winly first.

• Adding an existing tag or removing a tag that is already absent completes without duplicating or failing the change.

• Owner assignment removes the conversation from the previous owner's assigned view.

• An API key represents the account, not an individual teammate. Prefer OAuth for actions that should carry the acting user's identity.

Autopilot curation

These tools require the corresponding Autopilot data and configuration to be available in the account. Do not assume a tool result changed live AI behavior until the client reports success and the relevant Winly setting or record confirms it.

Review write actions safely

Before approving a write action:

1. Confirm the account and contact.

2. Review the complete message, new owner, tag, status, or configuration value.

3. Check whether the action can trigger a workflow or change who sees the conversation.

4. Approve the action once.

5. Verify the result in Winly before retrying.

Understand limits

If the client receives 429 Too Many Requests, wait before retrying. Do not repeatedly resubmit a write action because the original request may already have completed.

Manage or remove access

Review API keys

In Settings → MCP, the API-key table shows each active key's name, masked identifier, creation date, and last-used date. Use the last-used value to identify inactive or unexpected credentials.

Revoke an API key

1. Open Settings → MCP.

2. Find the intended key.

3. Select the trash icon.

4. Confirm Revoke.

Revocation takes effect immediately and cannot be undone. Any client using that key stops working. Create a replacement key and update the intended client if access is still required.

Disconnect OAuth

Remove or disconnect Winly from the MCP client's connection settings. If the client does not complete the disconnection or access appears to remain active, contact Support with the account name and client name. Never send an access token or API key to Support.

Troubleshoot MCP

For authorization failures, missing tools, rate limits, and connection checks, see Troubleshoot MCP connections.

Connect Claude.ai or Claude Desktop (Custom Connector, recommended)

This is the easiest way for anyone using Claude on the web or desktop. No API keys, no config files — Claude handles the OAuth handshake for you.

Steps (same on Claude.ai and Claude Desktop)

1. Open Settings → Connectors. (Newer Claude versions: there's a banner at the top saying "Connectors have moved to Customize" — you can manage them from either place.)

2. Scroll to the bottom of the connectors list and click Add custom connector.

3. A dialog pops up with two fields:

   • Name — type Winly (or whatever you like to call it).

   • Remote MCP server URL — paste your Revio MCP endpoint:

     https://app.sbccrm.com/bld/api/mcp

4. Click Add. Claude opens your browser to Revio's authorization page.

5. Log in to Winly with your normal credentials if you're not already signed in.

6. On the consent screen you'll see:

   • What Winly will let Claude do ("Read your contacts, conversations, and analytics" + "Send messages and update settings on your behalf")

   • Which Revio account you're authorizing as

   • Deny / Authorize buttons

7. Click Authorize. Your browser redirects back and Claude opens automatically (you may see an "Open Claude?" prompt — click Open).

8. You're returned to the Connectors screen. Click Revio to see all 28 tools listed under "Tool permissions".

Fine-tune tool permissions (optional)

On the Revio connector page in Claude, each tool has a permission control on the right:

• Always ask — Claude asks you before calling this tool (safest; recommended for write tools like send_dm, set_opens_config).

• Always allow — Claude uses the tool freely without asking (recommended for read-only analytics tools).

• Never — Tool is disabled entirely.

Use the Custom dropdown in the top right to set permissions in bulk.

To disconnect

• From Claude: Settings → Connectors → Winly → Uninstall.

• From Revio side: if you want to revoke a specific user's authorization server-side, contact your Customer Success rep.

If you have any trouble in accessing / connecting Claude to Revio share the following information

{

  "mcpServers": {

    "revio-crm": {

      "type": "url",

      "url": "https://app.sbccrm.com/bld/api/mcp",

      "headers": {

        "X-API-Key": "YOUR_API_KEY_HERE"

      }

    }

  }

}

Connect Claude Code (CLI)

Claude Code handles OAuth automatically — same as Claude.ai and Claude Desktop — just via the command line.

Option A — OAuth (recommended)

claude mcp add winly --transport http https://app.sbccrm.com/bld/api/mcp

What happens:

1. Claude Code pings the Revio server and discovers it requires OAuth.

2. Your browser opens to Revio's authorization page.

3. Log in to Revio (if not already), click Authorize.

4. You're redirected back. Claude Code stores the token and refreshes it automatically when it expires.

Verify:

claude mcp list

You should see Revio listed with status Connected.

Scope tip: By default the connection is scoped to your current project. To make Revio available in every Claude Code project on this machine, add --scope user:

claude mcp add revio --transport http --scope user https://app.sbccrm.com/bld/api/mcp

Option B — API key (headless / CI / non-browser environments)

Use this when you can't open a browser — e.g., running Claude Code on a CI server, inside a container, or over SSH.

Step 1 — Generate an API key in Revio

1. In Revio, go to Settings → MCP Settings.

2. Click Create API Key.

3. Name it descriptively (e.g., Claude Code – CI server). Use one key per machine/purpose.

4. Copy the full key immediately — it starts with mcp_ and is shown only once. If you lose it, revoke and mint a new one.

Step 2 — Add the server with the key as a header

claude mcp add revio \
  --transport http \
  -H "X-API-Key: mcp_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  https://app.sbccrm.com/bld/api/mcp

Advanced OAuth flags (optional)

If you need to pin the OAuth flow to specific pre-registered credentials (e.g., for SSO/compliance), Claude Code supports --client-id, --client-secret, and --callback-port. Contact your Customer Success rep if you need this path. For most users, Option A above is what you want.

Other MCP clients

Custom scripts, third-party IDEs, or Anthropic SDK apps can connect to Revio the same way:

• OAuth — if your client speaks the MCP OAuth spec (PKCE + Dynamic Client Registration), just point it at https://app.sbccrm.com/bld/api/mcp and it'll discover the auth flow.

• API key — otherwise, send X-API-Key: mcp_... as a header on every request.

6. Automate with Claude Routines (Claude Auto-Response)

Claude Routines are AI agents that live in Claude Desktop's sidebar and can be triggered on a schedule, by a GitHub event, or via a POST webhook. Revio uses the webhook trigger: every time a new DM arrives, Revio POSTs the contact's context to your Routine, which then uses its own MCP connection back to Revio to read the conversation and reply.

The setup is a two-way handshake:

Claude → gives you a URL and token → paste into Revio → Revio fires that URL on every new DM.

You'll end up with a fully customizable autopilot built in Claude, running alongside (or instead of) Revio's built-in Autopilot.

Prerequisites

• Revio is already connected as a custom connector in Claude Desktop (see Section 4).

• You're a Revio admin (needed to save the Auto-Response settings).

• Your Claude account has Routines available (newer Claude Desktop versions; check the sidebar).

Step 1 — Create the Routine in Claude Desktop

1. Open Claude Desktop. In the left sidebar, click Routines.

2. Click New routine (top right).

3. Fill in the form:

   • Name — e.g. DM Setter or Revio Autopilot

   • Description / instructions — this is the prompt Claude will follow on every trigger. A starter template:

     You are responding to a new Instagram DM from a Revio CRM lead.
     
     The trigger message will include a contact_id. Your job is to:
     1. Call the `ask_about_contact` MCP tool with that contact_id to read the
        recent conversation and any notes.
     2. Decide if a reply is warranted. If not, stop.
     3. If yes, draft a reply matching the tone of the existing conversation
        and call `send_dm` with contact_identifier set to the contact_id.
     
     Keep replies short, friendly, and on-brand. Never pitch product in the first reply.
     

   • Model — default is Opus 4.7; leave as-is unless you have a reason to change.

4. Under Select a trigger, pick API ("Trigger from your own code by sending a POST request"). This is the one Revio uses — not Schedule or GitHub event.

5. Switch to the Connectors tab. Confirm Revio is in the list (it should be there automatically if you connected it in Section 4). Remove any other connectors you don't want this Routine to use.

6. Optionally switch to the Permissions tab and review which tools this Routine is allowed to call. By default all tools from the selected connectors are allowed without approval during runs — tighten this if you're cautious.

7. Click Create.

Step 2 — Copy the Routine URL and API token from Claude

1. In your newly created Routine, click on the Call via API trigger chip. The Edit trigger dialog opens.

2. It shows:

   • URL — looks like https://api.anthropic.com/v1/claude_code/routines/trig_XXXXXXXXXXXXXXXX/fire

   • TOKEN — starts with sk-ant-oat01-...

3. Copy the URL (click the copy icon next to it).

4. Copy the token. If this is a new Routine, the token is visible. If you're returning later and the token is hidden, click Regenerate — note that this invalidates the previous token, so you'll need to paste the new one into Revio right after.

5. Click Done.

Step 3 — Paste them into Revio

1. Open Revio. In the sidebar, go to Settings → MCP.

2. At the top of the page you'll see the Claude Auto-Response section with a toggle.

3. Turn the toggle ON.

4. Routine URL field — paste the URL from Step 2.

5. API Token field — paste the token from Step 2.

6. Click Save.

After saving, the token field shows a masked preview (e.g. sk-ant-oa01-q6...1QAA) — that's expected. Revio never displays the full token back to you for security reasons. If you ever need to rotate it, just paste a new token into the field and save again.

Where does the API key section below come in? The MCP API Keys table below Claude Auto-Response is a separate feature — those keys are for Claude Desktop, Claude Code, or custom scripts that connect to Revio (see Sections 4 and 5). Claude Auto-Response is the other direction: Revio calling out to your Routine. You don't need an MCP API key for Claude Auto-Response to work.

Step 4 — Test end to end

1. From another Instagram account (or ask a teammate), send a test DM to your connected Instagram account.

2. Within a few seconds, Revio POSTs to your Routine's URL with a payload like:

   {
     "text": "A new instagram DM has been received. Use this contact_id to look up and respond:\n\ncontact_id: 68a1f2e34567…\ncontact_name: Jane Doe\nchannel: instagram\nlatest_message: \"hey, got your link\"\n\nCall the ask_about_contact MCP tool with contact_id=\"68a1f2e34567…\" to read the conversation, then call send_dm with contact_identifier=\"68a1f2e34567…\" to reply."
   }
   

3. Open the Routine in Claude Desktop → Routines → DM Setter → Runs. You should see a new run entry.

4. Click into the run. Verify:

   • Claude called ask_about_contact — you'll see the conversation history returned as JSON.

   • Claude called send_dm — you'll see Used send_dm in the run timeline.

5. Switch to Revio's inbox and open the conversation with the test contact. The reply from the Routine should appear as a sent message.

If nothing happens within 10 seconds, see the troubleshooting entry for Routines in Section 9.

Routines vs Autopilot

You can run both — use Routines for a specific segment (e.g. warm leads from a particular campaign) while Autopilot handles the rest. Or use Routines as a sandbox for new prompts before graduating them to Autopilot.

7. Rate limits

If you hit a limit, Claude will receive a 429 Too Many Requests response and will back off. For higher limits, contact your CS rep.

8. Security best practices

• Treat API keys like passwords. Don't share them, don't paste them into screenshots, don't commit them to git.

• One key per client. If you use Claude Desktop on your laptop and Claude Code on your server, generate two separate keys so you can revoke one without affecting the other.

• Rotate regularly. Revoke keys you no longer use from Settings → MCP Settings. Old keys stay active until you explicitly revoke them.

• OAuth over API keys when possible. OAuth tokens tie to your user identity and can be revoked globally in one place; API keys are longer-lived.

• Audit who has access. Only workspace admins should be authorizing MCP connections.

9. Troubleshooting

"401 Unauthorized" / "Invalid API key"

• Double-check the X-API-Key header is set correctly (exact header name, no spaces).

• Confirm the key hasn't been revoked — check Settings → MCP Settings.

• Confirm the URL matches your workspace domain.

"429 Too Many Requests"

You've hit the 30/min or 3-concurrent limit. Wait a minute and retry.

OAuth authorization gets stuck

• Make sure you're logged into Revio in the same browser tab before Claude redirects you.

• Try in an incognito window if your browser has stale cookies.

Claude Routine isn't firing on new DMs

1. Go to Settings → MCP Settings → Claude Routine Trigger and confirm the URL and token are saved (token field will show masked — that's expected).

2. Send a test DM and check the Routine's run history in Claude.ai for any received triggers.

3. If no trigger was received, check with CS that webhook delivery is enabled for your workspace.

"Tool not found" when Claude tries to call a Revio tool

• You may be on a plan that doesn't include that tool. Check the tool list in section 2.

• Confirm the MCP connection is fully authorized (some tools require Pro tier).

10. FAQ

Q: Does connecting MCP replace the Revio dashboard or Autopilot? No. MCP is an additional interface — the dashboard, inbox, workflows, and Autopilot all continue to work unchanged. MCP just gives you another way to query and act on the same underlying data.

Q: Can Claude see my customer conversations? Only when you (or a Routine you configured) explicitly ask Claude to call a Revio tool that reads messages. Claude does not continuously sync your data.

Q: Does every Claude tool call count toward my rate limit? Yes. Each MCP tool call from Claude is one request. A single Claude answer may make several tool calls.

Q: Can I restrict which tools are available? Contact your CS rep. All 28 tools are exposed by default; Pro-tier Autopilot tools are opt-in at the workspace level.

Q: What's the difference between OAuth and API-key auth? OAuth ties the connection to your Revio user identity and supports revocation from both sides. API keys are long-lived credentials you manage manually. For Claude.ai, use OAuth. For Claude Desktop or custom scripts, use API keys.

Q: Can I use this with ChatGPT or other LLMs? The MCP connector is built to the open MCP spec, so any MCP-compatible client can connect. However, Revio officially supports Claude. Other clients are "bring your own support."

Q: How do I cancel or disconnect?

• OAuth: Claude.ai → Settings → Connectors → Revio → Remove.

• API keys: Revio → Settings → MCP Settings → find the key → Revoke.

• Claude Routine trigger: Revio → Settings → MCP Settings → clear the Routine Trigger URL and save.