Velaro MCP API Gateway

The Velaro MCP API Gateway exposes Velaro's AI skill suite as a standard Model Context Protocol (MCP) endpoint. This allows external AI agents, Claude Desktop, Cursor IDE, and custom automation tools to call Velaro's skills using scoped API keys — without needing a Velaro user account.

---

What Is an API Key?

An API key is a credential that lets an external tool act on behalf of your Velaro site. It is not tied to a user account. The key carries:

• Your site identity — all calls are scoped to your account
• Scopes — which categories of skills the key can call
• Monthly quota — how many calls are allowed per billing month
• Optional expiry — auto-expires if you set a date

---

Creating an API Key

1. Go to Admin → Settings → API Keys

2. Click Create Key

3. Enter a label (e.g., "Claude Desktop", "n8n automation", "Internal reporting bot")

4. Select scopes — check each category your external tool needs access to

5. Optionally set an expiry date

6. Click Create — the vel_live_... key is shown once only. Copy it immediately.

> Security note: Velaro stores only a SHA-256 hash of your key. If you lose it, revoke it and create a new one. Keys cannot be recovered.

---

Using the API Key

Add the key as a Bearer token in the Authorization header:

Authorization: Bearer vel_live_YOUR_KEY_HERE

Base URL:

https://your-site.velaro.com/mcp/v1

---

Connecting to Claude Desktop

Add this to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "velaro": {
      "type": "http",
      "url": "https://your-site.velaro.com/mcp/v1",
      "headers": {
        "Authorization": "Bearer vel_live_YOUR_KEY_HERE"
      }
    }
  }
}

After restarting Claude Desktop, type /mcp in Claude to see available Velaro tools.

---

Connecting to Cursor IDE

Add to .cursor/mcp.json in your project:

{
  "velaro": {
    "url": "https://your-site.velaro.com/mcp/v1",
    "authorization": "Bearer vel_live_YOUR_KEY_HERE"
  }
}

---

Available Skill Categories (Scopes)

| Scope | What it includes |

|-------|-----------------|

| Commerce | Shopify, BigCommerce, WooCommerce, Magento — orders, products, customers, inventory, coupons, returns |

| CRM | HubSpot, Dynamics 365, Salesforce, NetSuite, Velaro Native CRM — contacts, deals, cases, activities |

| ITSM | ServiceNow — incidents, service requests, changes, problems, knowledge base, assets |

| Civic | Accela — permits, service requests, inspections, parcel lookups |

| Marketing | Klaviyo — event tracking, list management, profile updates |

| Communications | Send SMS, send email, click-to-call, schedule callback |

| Automation | Trigger Zapier Zaps, Power Automate flows, Make.com scenarios |

| Campaigns | Create and manage drip campaigns, enroll/unenroll contacts |

| Appointments | Square appointment booking — check availability, book, cancel |

| Ops | List agents, usage inquiry, product help |

Only skills within your selected scopes are callable. Requesting a skill outside your scopes returns HTTP 403.

---

API Reference

List Available Tools

curl -X GET https://your-site.velaro.com/mcp/v1/tools/list \
  -H "Authorization: Bearer vel_live_..."

Returns a JSON list of all tools your key has access to, including their input schemas.

Call a Tool

curl -X POST https://your-site.velaro.com/mcp/v1/tools/call \
  -H "Authorization: Bearer vel_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "shopify_get_order",
      "arguments": {
        "orderId": "5001234567890"
      }
    },
    "id": 1
  }'

Manage Keys via API

# Create a key
POST /mcp/v1/keys

# List your keys
GET /mcp/v1/keys

# Revoke a key (instant)
DELETE /mcp/v1/keys/{id}

---

Example Use Cases

Ops Manager asking Claude

> "How many conversations did support handle this week, and how does it compare to last week?"

With the Ops scope enabled, Claude calls velaro_get_conversation_stats and returns a summary.

Customer service automation (n8n / Make.com)

An automation workflow receives a new Shopify order, calls shopify_get_order via the Velaro MCP, enriches it with hubspot_search_contact, then creates a HubSpot task via hubspot_create_task — all without writing code.

IT helpdesk AI agent

A ServiceNow-connected agent calls servicenow_create_incident when a user reports a problem via chat. The agent automatically assigns the incident and adds work notes — the agent never needs to log into ServiceNow.

Sales team assistant (Cursor/Claude Desktop)

A sales rep types in Claude: "Find all open deals over $50k that haven't had activity in 30 days" — Claude calls hubspot_search_deals with filters and returns a formatted list.

Reporting bot (scheduled)

A nightly workflow calls reporting skills to build a daily performance summary and emails it to team leads via velaro_send_email.

---

Usage Limits

Your API key usage counts against your plan's MCP call quota. You can view current usage in Admin → Settings → Billing.

| Plan | MCP Calls / Month |

|------|--------------------|

| Trial | Not available |

| Professional | 5,000 |

| Enterprise | 50,000 |

When you approach your limit, usage alerts fire (if enabled). Contact sales to increase your quota or enable overage billing.

---

Security Best Practices

• One key per integration — create separate keys for Claude Desktop, automation tools, and reporting bots. This lets you revoke one without affecting others.
• Minimum scopes — only enable the scopes your integration actually needs
• Set expiry dates — for temporary integrations (demos, contractors), always set an expiry
• Rotate keys periodically — revoke and recreate keys every 90 days for sensitive integrations
• Never share keys — keys are like passwords; each person or system should have their own

---

Revoking a Key

Go to Admin → Settings → API Keys, find the key, and click Revoke. Revocation is instant — all calls using that key return HTTP 401 immediately.

---

Plan Requirements

MCP API Gateway is available on Professional and Enterprise plans. To enable it on your account, contact your account manager or upgrade your plan.