MCP Server

MCP is a first-class citizen in Vendo. Your AI can work with the same operations that you use in the app through tools on the Model Context Protocol . These include sources, syncs, integrations, jobs, models, optimization and more.

The Vendo Agent and MCP use the same Vendo tools. Through MCP, your AI agent can query your data and manage sources, destinations, jobs, models, metrics, documents, charts and tasks. Use Vendo in your favorite AI agent, for example Claude, ChatGPT, Cursor or Codex. Some features are only in the Agent in the Vendo app, for example charts and tables in the chat and scheduled analyses.

The Vendo MCP server is a remote HTTP server on the Vendo web app. You add it to your client with an mcpServers JSON object (the same pattern as other hosted MCP servers). Then you sign in with OAuth or, when needed, a Vendo API key.

In-app help: In Vendo, open Workspace Settings → Developers → MCP for copy-paste JSON tailored to your workspace URL. You need the api_keys.admin permission to see this page.

Before you connect

Connecting an LLM to your data has risks (for example prompt injection in user-generated content that an assistant might read through tools). We recommend:

• Prefer read-only access when the assistant only needs to inspect data. Use OAuth scope mcp:read, or an API key with the MCP read only scope. With a Full access key, add read_only=true to the MCP URL.
• Keep tool approval on in your IDE and review each tool call before accepting.
• Use OAuth when your client supports it so you approve access in the browser.
• Protect API keys like production secrets. In config, prefer environment variables (for example ${VENDO_API_KEY}) to keys pasted into files that you might commit.

Endpoint

https://app2.vendodata.com/api/mcp

Use your team’s Vendo URL if different. During the design partner alpha, the app is at https://app2.vendodata.com . The path is always /api/mcp.

Discovery (optional):

• OAuth metadata: /.well-known/oauth-authorization-server
• OAuth protected resource metadata: /.well-known/oauth-protected-resource/api/mcp
• MCP manifest: /.well-known/mcp.json

Generate a key on the MCP page

The MCP page creates an API key and puts it into the client snippets for you.

Warning: If the client only needs to read data, do not use Generate key. It creates a key with Full access, which can use the REST API and the MCP write tools. Create a key with the MCP read only scope on the API Keys page.

1. In the account dropdown menu, click Workspace Settings.
2. Under Developers, click MCP.
3. Click Generate key.
4. Copy the token under Save this token now.
5. In Connect from, select your client.
6. Copy the JSON config snippet.
7. If your client is Claude, you can copy the CLI snippet instead.

The page shows the full token only once. Until you leave the page, the snippets contain the token in place of ${VENDO_API_KEY}.

The key is named MCP (<date>). You can see it on the API Keys page. The key acts with the current workspace access of the user who created it. If the role of that user changes, the access of connected clients changes too.

The numbered steps under each snippet in the app say Settings → API Keys. The full path is Workspace Settings → Developers → API Keys.

API key scopes

When you create a key on the API Keys page, you select one scope. See Authentication.

A key without write scope is always read-only, whatever the URL says. The read_only parameter can only remove tools. It cannot add write tools.

Configure your client (JSON)

Most MCP clients accept a JSON file (often named mcp.json) or an equivalent setting in the app. Add a server under mcpServers with:

• "type": "http": remote streamable HTTP MCP
• "url": your MCP endpoint (see below for query parameters)
• "headers": only when you use a Vendo API key (Bearer token)

Option A — API key in headers (manual auth)

Create an API key in Vendo under Workspace Settings → Developers → API Keys. Then use:

{
  "mcpServers": {
    "vendo": {
      "type": "http",
      "url": "https://app2.vendodata.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${VENDO_API_KEY}"
      }
    }
  }
}

Set VENDO_API_KEY to your vendo_sk_… key in your environment, or replace the placeholder with the key only in a private, non-committed config.

Not every client supports custom headers. Check your client’s documentation.

Option B — Read-only tools (API key)

Append a query parameter so only read-only tools are registered:

{
  "mcpServers": {
    "vendo": {
      "type": "http",
      "url": "https://app2.vendodata.com/api/mcp?read_only=true",
      "headers": {
        "Authorization": "Bearer ${VENDO_API_KEY}"
      }
    }
  }
}

Option C — OAuth (no Bearer in JSON)

If your client supports MCP OAuth, add the MCP URL only (with type: "http") and complete your client’s login flow. The client should discover /.well-known/oauth-authorization-server on the Vendo host. During authorization you will:

1. Sign in with your Vendo user
2. Choose the team account to connect
3. Approve mcp:read (read-only) or mcp:write (read and write)

For OAuth, the URL does not control read-only or read-write access. You choose it at authorization time.

URL parameters

You can append these to the url string (API key flows and some clients):

Platform-specific notes

OpenAI Codex

codex mcp add vendo --url https://app2.vendodata.com/api/mcp
codex mcp login vendo --scopes mcp:read

For write access: --scopes mcp:write. Start a new Codex session after adding the server so config reloads.

Claude Code

You can register from the terminal (options before the server name):

claude mcp add --transport http \
  --header "Authorization: Bearer YOUR_VENDO_SK_KEY" \
  vendo \
  "https://app2.vendodata.com/api/mcp"

Or use the same mcpServers JSON as above if your Claude Code version merges global MCP config from a file.

Cursor, Windsurf, and other IDEs

Use Workspace Settings → Developers → MCP (or your client’s JSON config) and paste the mcpServers block from Configure your client. For Windsurf, the snippet in Workspace Settings → Developers → MCP uses serverUrl in place of type and url. If tools do not appear, restart the IDE.

VS Code

VS Code uses a servers key in place of mcpServers. Vendo shows this config for .vscode/mcp.json in your project root:

{
  "servers": {
    "vendo": {
      "type": "http",
      "url": "https://app2.vendodata.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${VENDO_API_KEY}"
      }
    }
  }
}

Replace ${VENDO_API_KEY} with your API key. Then use Copilot Chat to work with your Vendo data.

ChatGPT

Vendo shows the standard mcpServers JSON from Configure your client. In ChatGPT, add Vendo as an MCP server. Enter the MCP endpoint URL and your API key.

Google Gemini

Vendo shows the standard mcpServers JSON from Configure your client. In Google AI Studio, add Vendo as an MCP server. Enter the MCP endpoint URL and your API key.

Perplexity

Vendo shows the standard mcpServers JSON from Configure your client. Add Vendo as an MCP server in the Perplexity settings. Use the JSON with your API key.

Lovable

Vendo shows the standard mcpServers JSON from Configure your client. In the Lovable project settings, add an MCP server. Use the JSON with your API key.

Menu names in other products can change. If you cannot find the MCP setting, see the documentation for your client.

Other MCP clients

If the client supports remote HTTP MCP, use type, url, and headers as documented. If it only supports OAuth, use the URL and complete the built-in login flow.

Supported platforms

Prerequisites

1. A Vendo account with access to the team workspace you want to connect
2. An MCP-compatible client with remote HTTP (or OAuth) support
3. For API key auth: a key from Workspace Settings → Developers → API Keys

Available tools

The server registers tools dynamically from the current product registry. Your client’s connected tool list is authoritative. A copied count or exhaustive list in documentation would become stale as capabilities are added.

Typical capability families include:

Mutation tools appear only when the session is read-write. When a tool is called, Vendo checks the current workspace permissions of the connected user. A read-only connection does not merely block execution after a call. Mutation tools are omitted from registration.

Access modes (OAuth)

When you authorize with OAuth, you choose:

• mcp:read: read-only (mutation tools are not registered)
• mcp:write: full tool surface for allowed operations

To upgrade from read-only to write, run your client’s MCP login or authorization again and approve mcp:write.

Authentication summary

Rate limits

MCP traffic that uses an API key counts against the limits of that key. The defaults are below. Your workspace may differ.

Usage examples

Infrastructure

“List my active Shopify sources"
"Create a new Google Ads source for my production app”

Monitoring

“What is the status of my latest sync jobs?"
"Why did my Google Ads integration fail?”

Actions (requires write access)

“Pause my Stripe integration"
"Trigger a sync for my Shopify source”

Models

“Create a data model that joins orders with customer profiles”

Troubleshooting

Unauthorized

• OAuth: run login again. Confirm that you selected the correct team account.
• API key: confirm the key is active and the Authorization header is correct
• Restart the client after changing MCP config

Connection timeouts

• Vendo uses streamable HTTP. Restrictive proxies may interfere. Try another network or read-only mode first.

Tools missing

• Read-only sessions hide mutation tools
• A key with the MCP read only scope hides mutation tools, whatever the URL says
• After scope or URL changes, reconnect or restart the client

Security considerations

• Prefer OAuth for interactive use
• Use mcp:read, an MCP read only key or read_only=true when mutations are not needed
• Avoid committing API keys. Use env substitution in JSON where supported.
• Review tool calls before approving in your IDE

Related

• Authentication: API keys and request auth
• Apps: App resources
• Error handling: errors and X-Request-Id