How to Use the Convex MCP in Claude

Q: Can Claude Desktop run Convex actions that call external APIs?

Yes. When you invoke runaction inside Claude Desktop, the request runs directly on your Convex backend. Any external API calls or Node.js environment tasks defined in your action execute exactly as they would in production.

Q: What happens if a query returns too much data?

The runquery tool passes the JSON payload back to your agent. If the payload is massive, you should write a specific query function that limits or paginates the results to avoid hitting context window limits.

Run your Convex queries and mutations directly inside Claude Desktop to inspect and modify backend state in real time.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect Convex MCP to Claude Desktop

Create your Vinkius account to connect Convex to Claude Desktop and route execution through our secure gateway. The platform manages server hosting, runtime updates, and security layers. Configuration requires no manual server provisioning.

GDPR Free for Subscribers

Setup Convex with Claude Desktop

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Run live database queries in Claude Desktop

The `run_query` tool fetches live data from your Convex database directly into your Claude Desktop chat window. You don't have to jump back and forth to your web dashboard to see what's in your tables. Just ask your agent to pull the latest records, and it runs the query immediately. This means your Claude Desktop agent works with real-time state when debugging. If a user reports a bug, you can tell the agent to inspect their specific document ID, letting it analyze the actual data causing the issue.

Execute mutations directly from Claude Desktop

You can write new data or modify existing records using the `run_mutation` tool from your Claude Desktop interface using this MCP Server. Instead of writing throwaway scripts to fix bad database state, you tell your agent what needs to change. It translates your intent into a precise database write. This changes how you handle quick administrative tasks. You can ask your agent to flag a user account or patch a broken schema field, and the write executes safely through your existing Convex mutation logic.

Trigger complex Convex actions inside this MCP Server

The `run_action` tool handles side effects like sending emails or calling third-party APIs from your Claude Desktop session. Since actions in Convex run in a Node.js environment, you can trigger these multi-step workflows without leaving your conversation. You can also execute generic backend functions using `run_function` when you need to run logic that doesn't fit a standard query or mutation. Your agent handles the payload formatting, so you only need to specify the function path and the arguments.

Setup guide

Set up Convex MCP in Claude Web or Desktop

1

Open Claude Settings

Go to claude.ai, click your profile icon, then navigate to Customize → Connectors.
2

Add Custom Connector

Click the "+" button and select Add custom connector. Paste your Vinkius endpoint URL: https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp Replace [YOUR_TOKEN_HERE] with your token from cloud.vinkius.com. For OAuth-protected servers, expand Advanced settings to add credentials.
3

Start a conversation

Open a new chat. The Convex MCP tools are available immediately — no restart needed.

Endpoint URL

https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp

No configuration file needed — paste the URL directly in the Claude web interface.

Available on Free (1 connector), Pro, Max, Team, and Enterprise plans.

Prerequisites

Claude Desktop installed (macOS or Windows)
Active Vinkius subscription with a valid endpoint token

1

Open Claude Desktop Settings

Click the menu icon at the top-left corner, go to Settings → Developer → Edit Config. This opens claude_desktop_config.json in your default text editor.
2

Paste the Convex MCP configuration

Copy the JSON snippet on the right into the mcpServers object. Replace [YOUR_TOKEN_HERE] with your endpoint token from cloud.vinkius.com.
3

Restart Claude Desktop

Close and reopen the application. Claude needs a full restart to load new MCPs — refreshing a conversation is not enough.
4

Verify the connection

Open a new conversation. Click the 🔌 icon at the bottom of the message input. You should see tools listed under convex-mcp.

json

{
  "mcpServers": {
    "convex-mcp": {
      "url": "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
    }
  }
}

Get your connection token →

Independent Platform Disclaimer: Vinkius is an independent platform and is not affiliated with, endorsed by, sponsored by, verified by, or otherwise authorized by Convex. All third-party trademarks, logos, and brand names are the property of their respective owners. Their use on this website is strictly for informational purposes to identify service compatibility and interoperability.

Why Choose Vinkius

Vinkius connects your tools to AI with real-time monitoring and automatic cost savings — all from one dashboard.

Connect Convex now

Real-time monitoring

Live

visibility into every interaction

Connect your favorite tools to your AI and see exactly what's happening — every request, every response, in real time.

Built-in savings

60%

lower AI costs

Vinkius compresses data between your apps and your AI automatically. Lower bills every month — no configuration required.

Single dashboard

One

place for every integration

Every tool your AI connects to, managed from a single screen. One account, complete control.

Common questions about Convex MCP in Claude Desktop

You define your mutation logic in your Convex schema as usual, and then use `run_mutation` through the Claude Desktop interface. The MCP Server respects your existing backend validation rules. If a mutation would fail on your server, it fails safely in your chat.

Yes. When you invoke `run_action` inside Claude Desktop, the request runs directly on your Convex backend. Any external API calls or Node.js environment tasks defined in your action execute exactly as they would in production.

No. Vinkius manages the connection securely using a single endpoint token. Your Claude Desktop client only needs this token to securely communicate with the managed MCP Server, keeping your master database keys hidden.

The `run_query` tool passes the JSON payload back to your agent. If the payload is massive, you should write a specific query function that limits or paginates the results to avoid hitting context window limits.

Your Convex database records and mutation payloads are processed in an ephemeral, zero-trust V8 Isolate sandbox. Vinkius does not store your query results or write payloads. The data passes directly between your Convex deployment and your local client, then the sandbox is immediately destroyed.

Use it with your favorite AI tools

Connect this server to Cursor, Claude, VS Code, and more.

OpenAI Agents SDK sdk-python

Google ADK sdk-python

Pydantic AI sdk-python

Vercel AI SDK sdk-typescript